mailbox_gem 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fa8d40772489423cacc25cb31361764217a829ea682e0feaabae1c7ad9a8ac7f
+  data.tar.gz: a4c11a6abf57765980328193a6dab0e212e74edfc2d207b9c603cd54be67ca05
+SHA512:
+  metadata.gz: f3be8e4cf7f0b2e8a88d4a707f1000f151917df1a5991006d6f1b421ed5e76f657254a175e522181a6add6264472cbfc24c8c104dfdcc35494e75c29d7f35d50
+  data.tar.gz: 83b0fffc3a4130c43db73c44e2232c93d700a39bf11505d28d0045abe4b061f1747478815d440c0aebab4051d24821108a9dd8e97e8c5bfd744aeba0b255e176

data/README.md

@@ -0,0 +1,111 @@
+# MailboxGem
+
+<img width="1774" height="887" alt="mailbox_banner" src="https://github.com/user-attachments/assets/a8c594e1-8e11-48e1-ad3c-fe71fa25b317" />
+
+
+A development-only email inbox for Rails, inspired by [Phoenix's `/dev/mailbox`](https://hexdocs.pm/swoosh/Swoosh.Adapters.Local.html). Point `ActionMailer` at it in development and every email your app actually sends — through its real mailer code paths, not a hand-written preview — shows up in a live, searchable inbox in your browser.
+
+MailboxGem is a standalone engine. It doesn't modify Rails or Action Mailer; it registers itself as one more delivery method, the same extension point `letter_opener` and `mailcatcher` use.
+
+## Why
+
+Rails already has two ways to look at outgoing mail in development, and both have a gap:
+
+- **`ActionMailer::Preview`** (`/rails/mailers`) renders a mailer against data you construct by hand in a preview class. It never touches your real application code path, so it can drift from what actually gets sent.
+- **`ActionMailer::Base.deliveries`** only accumulates anything when `delivery_method` is `:test`, which is what the `test` environment uses — not `development`. In development there's normally nowhere to look at all.
+
+MailboxGem fills that gap: it captures the real `Mail::Message` your app hands to Action Mailer when a user actually triggers an email (signs up, resets a password, checks out), and gives you a live UI to inspect it — HTML, plain text, and raw source, with attachments.
+
+## Features
+
+- **Captures real mail**, not previews — anything delivered through Action Mailer while `mailbox_gem` is the active delivery method.
+- **Live-updating inbox** — the message list polls in the background and updates without a page reload.
+- **Search-as-you-type** — filters by from/to/subject with no page reload and no query language, debounced so it doesn't hammer the server.
+- **HTML / Text / Source tabs** per message, with attachments listed and sized. HTML is rendered in a sandboxed `iframe` — captured mail is untrusted content and never executes scripts against your app's page.
+- **Zero-config storage** — in-memory only, no database, no migration to install.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 8.0
+
+## Installation
+
+Add it to your `development` group — this is a dev tool and has no reason to load in `production` or `test`:
+
+```ruby
+group :development do
+  gem "mailbox_gem"
+end
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+**1. Mount the engine**, guarded to development, wherever you'd like it served from:
+
+```ruby
+# config/routes.rb
+mount MailboxGem::Engine => "/mailbox" if Rails.env.development?
+```
+
+**2. Point Action Mailer at it:**
+
+```ruby
+# config/environments/development.rb
+config.action_mailer.delivery_method = :mailbox_gem
+```
+
+**3. Visit `/mailbox`** and send some mail from your app. It'll show up without you doing anything else.
+
+Both steps are opt-in on purpose. Mounting is a normal route in your own `config/routes.rb`, and the delivery method only takes effect if you assign it — installing the gem never silently changes how your app already handles mail in development (e.g. if you're already using `letter_opener` or a local SMTP catcher).
+
+## Configuration
+
+MailboxGem keeps the most recent messages and drops older ones once that limit is exceeded:
+
+```ruby
+# config/initializers/mailbox_gem.rb
+MailboxGem.max_messages = 500 # defaults to 200
+```
+
+## Known limitations
+
+- **In-memory only.** The mailbox is wiped on every server restart. This is deliberate — the same tradeoff `ActionMailer::Base.deliveries` makes — not a bug.
+- **Single Puma worker only.** Storage is a plain in-process buffer. If your app runs Puma in cluster mode (`WEB_CONCURRENCY > 1`), each worker process gets its own independent mailbox, and the UI will only show whatever mail happened to land on whichever worker served that request. This is fine under Puma's default (`WEB_CONCURRENCY` unset, i.e. one worker); it's a real gap if you deliberately run multiple workers in development.
+
+## Development
+
+```bash
+bundle install # installs dependencies for the gem and its dummy test app
+bin/rails test # runs the test suite against the dummy app
+bin/rubocop    # lints
+```
+
+The dummy Rails app used for manual testing lives under `test/dummy`.
+
+### Testing against multiple Rails versions
+
+`mailbox_gem.gemspec` declares `"rails", ">= 8.0"`. CI backs that claim by running the suite against each supported minor via [Appraisal](https://github.com/thoughtbot/appraisal) - see `Appraisals` and the generated `gemfiles/*.gemfile`:
+
+```bash
+BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bin/rails test
+BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bin/rails test
+```
+
+After changing `Appraisals` or the gemspec's dependencies, regenerate and commit the gemfiles:
+
+```bash
+bundle exec appraisal generate
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome. This gem is meant to stay small and dependency-light — before adding a new capability, it's worth asking whether it fits a zero-config, drop-in dev tool, or belongs as configuration a host app opts into instead.
+
+## License
+
+Released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

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

data/app/assets/javascripts/mailbox_gem/application.js

@@ -0,0 +1,5 @@
+import { Application } from "@hotwired/stimulus"
+import AutoRefreshController from "mailbox_gem/controllers/auto_refresh_controller"
+
+const application = Application.start()
+application.register("auto-refresh", AutoRefreshController)

data/app/assets/javascripts/mailbox_gem/controllers/auto_refresh_controller.js

@@ -0,0 +1,58 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Keeps resultsTarget in sync with baseUrlValue+queryValue two ways: a
+// periodic poll (new mail arriving), and live as the user types in the
+// search input (debounced, so it's not one fetch per keystroke).
+//
+// Only resultsTarget's contents are ever replaced, never the controller's
+// own element - the search input has to survive a refresh mid-keystroke.
+//
+// Progressive enhancement: the form is a real GET fallback if this never
+// connects (JS disabled). #submit prevents that navigation when it can,
+// since a full page reload defeats the point of "no reload" search.
+export default class extends Controller {
+  static targets = [ "results", "search" ]
+  static values = {
+    baseUrl: String,
+    query: String,
+    interval: { type: Number, default: 3000 },
+    debounce: { type: Number, default: 300 },
+  }
+
+  connect() {
+    this.requestId = 0
+    this.timer = setInterval(() => this.refresh(), this.intervalValue)
+  }
+
+  disconnect() {
+    clearInterval(this.timer)
+    clearTimeout(this.debounceTimer)
+  }
+
+  search(event) {
+    this.queryValue = event.target.value
+
+    clearTimeout(this.debounceTimer)
+    this.debounceTimer = setTimeout(() => this.refresh(), this.debounceValue)
+  }
+
+  submit(event) {
+    event.preventDefault()
+    clearTimeout(this.debounceTimer)
+    this.refresh()
+  }
+
+  async refresh() {
+    const url = this.queryValue
+      ? `${this.baseUrlValue}?q=${encodeURIComponent(this.queryValue)}`
+      : this.baseUrlValue
+
+    // The debounced keystroke fetch and the periodic poll can race; a slow
+    // response for an older query shouldn't ever overwrite a newer one.
+    const requestId = ++this.requestId
+    const response = await fetch(url, { headers: { Accept: "text/html" } })
+    if (response.ok && requestId === this.requestId) {
+      this.resultsTarget.innerHTML = await response.text()
+    }
+  }
+}

data/app/assets/stylesheets/mailbox_gem/application.css

@@ -0,0 +1,263 @@
+:root {
+  /* Ruby Brand */
+  --ruby: #CC342D;
+  --ruby-dark: #A91401;
+  --rails: #D30001;
+
+  /* Neutrals */
+  --bg: #F8FAFC;
+  --surface: #FFFFFF;
+  --surface-alt: #F3F4F6;
+
+  --text: #1E1E1E;
+  --muted: #6B7280;
+  --border: #E5E7EB;
+
+  /* Accent */
+  --link: #3B82F6;
+  --success: #16A34A;
+
+  --radius: 8px;
+}
+
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  color: var(--text);
+  background: var(--bg);
+  margin: 0;
+  padding: 2rem;
+}
+
+h1 {
+  margin: 0 0 1rem;
+  font-size: 2rem;
+  font-weight: 700;
+  color: var(--ruby);
+}
+
+.mailbox-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1rem;
+}
+
+.back-link {
+  display: inline-block;
+  margin-bottom: 1rem;
+  color: var(--muted);
+  text-decoration: none;
+  font-size: 0.875rem;
+}
+
+.back-link:hover {
+  color: var(--ruby);
+}
+
+.search-form {
+  display: flex;
+  gap: .5rem;
+  margin-bottom: 1rem;
+}
+
+.search-input {
+  flex: 1;
+  padding: .5rem .75rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  font-size: .875rem;
+  color: var(--text);
+  background: var(--surface);
+  width: 234px;
+  padding-left: 2.2rem;
+}
+
+.search-input:focus {
+  outline: none;
+  border-color: var(--ruby);
+}
+
+.search-submit {
+  padding: .5rem 1rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  color: var(--text);
+  font-size: .875rem;
+  cursor: pointer;
+}
+
+.search-submit:hover {
+  border-color: var(--ruby);
+  color: var(--ruby);
+}
+
+.search-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  position: absolute;
+  left: .75rem;
+  top: 50%;
+  transform: translateY(-50%);
+  opacity: 50%;
+
+}
+
+.search-input-wrapper {
+  display: flex;
+  align-items: center;
+  flex: 1;
+  position: relative;
+
+}
+
+.clear-button {
+  display: block;
+  margin: 0 0 0.75rem auto;
+  background: var(--surface);
+  border: 1px solid var(--ruby);
+  color: var(--ruby);
+  border-radius: var(--radius);
+  padding: .45rem .9rem;
+  font-size: .8rem;
+  cursor: pointer;
+  transition: .2s;
+}
+
+.clear-button:hover {
+  background: var(--ruby);
+  color: white;
+}
+
+table.messages {
+  width: 100%;
+  border-collapse: collapse;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow: hidden;
+}
+
+table.messages th,
+table.messages td {
+  text-align: left;
+  padding: .75rem 1rem;
+  border-bottom: 1px solid var(--border);
+  font-size: .875rem;
+}
+
+table.messages th {
+  background: rgba(204, 52, 45, .06);
+  color: var(--ruby-dark);
+  font-weight: 600;
+}
+
+table.messages tbody tr:hover {
+  background: rgba(204, 52, 45, .04);
+}
+
+table.messages tbody tr:last-child td {
+  border-bottom: none;
+}
+
+table.messages a {
+  color: var(--link);
+  text-decoration: none;
+}
+
+table.messages a:hover {
+  color: var(--ruby);
+}
+
+.empty-state {
+  color: var(--muted);
+}
+
+.empty-state code {
+  background: rgba(204, 52, 45, .08);
+  color: var(--ruby-dark);
+  padding: .15rem .4rem;
+  border-radius: 4px;
+}
+
+dl.headers {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 1rem;
+  margin-bottom: 1rem;
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: .35rem 1rem;
+}
+
+dl.headers dt {
+  color: var(--ruby-dark);
+  font-weight: 600;
+}
+
+dl.headers dd {
+  margin: 0;
+}
+
+nav.tabs {
+  display: flex;
+  gap: .5rem;
+  margin-bottom: 1rem;
+}
+
+nav.tabs .tab {
+  padding: .45rem .9rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius);
+  color: var(--muted);
+  text-decoration: none;
+  transition: .2s;
+}
+
+nav.tabs .tab:hover {
+  color: var(--ruby);
+}
+
+nav.tabs .tab.active {
+  background: rgba(204, 52, 45, .08);
+  border-color: rgba(204, 52, 45, .2);
+  color: var(--ruby);
+  font-weight: 600;
+}
+
+.body-frame,
+.body-text {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+}
+
+.body-frame {
+  width: 100%;
+  height: 60vh;
+}
+
+.body-text {
+  padding: 1rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-size: .875rem;
+}
+
+ul.attachments {
+  padding-left: 1.25rem;
+  font-size: .875rem;
+}
+
+ul.attachments li::marker {
+  color: var(--ruby);
+}
+
+.muted {
+  color: var(--muted);
+}

data/app/controllers/mailbox_gem/application_controller.rb

@@ -0,0 +1,4 @@
+module MailboxGem
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/mailbox_gem/messages_controller.rb

@@ -0,0 +1,35 @@
+module MailboxGem
+  class MessagesController < ApplicationController
+    def index
+      @query = params[:q].presence
+      @messages = filtered_messages
+    end
+
+    # Polled by the auto-refresh Stimulus controller - same data as #index,
+    # rendered without the surrounding page so it can replace just the table.
+    # Takes the same q param so a poll mid-search stays scoped to it instead
+    # of silently reverting to the unfiltered list.
+    def table
+      @query = params[:q].presence
+      render partial: "table", locals: { messages: filtered_messages, query: @query }
+    end
+
+    def show
+      @message = Store.find(params[:id])
+      return head :not_found unless @message
+
+      @view = params[:view].presence || (@message.html_body ? "html" : "text")
+    end
+
+    def clear
+      Store.clear
+      redirect_to messages_path
+    end
+
+    private
+
+    def filtered_messages
+      Store.all.select { |message| message.matches?(@query) }
+    end
+  end
+end

data/app/helpers/mailbox_gem/application_helper.rb

@@ -0,0 +1,4 @@
+module MailboxGem
+  module ApplicationHelper
+  end
+end

data/app/jobs/mailbox_gem/application_job.rb

@@ -0,0 +1,4 @@
+module MailboxGem
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/mailbox_gem/application_mailer.rb

@@ -0,0 +1,6 @@
+module MailboxGem
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/mailbox_gem/application_record.rb

@@ -0,0 +1,5 @@
+module MailboxGem
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

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

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Mailbox gem</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "mailbox_gem/application", media: "all" %>
+
+  <%# Hand-written import map, not the importmap-rails gem: we only have a
+      fixed handful of modules, and this avoids requiring the host app to
+      manage config/importmap.rb for a UI that lives entirely on its own
+      page. asset_path resolves each specifier to its Propshaft-fingerprinted
+      URL, which is why this has to be rendered server-side rather than
+      living in a static JS file. %>
+  <script type="importmap">
+    {
+      "imports": {
+        "@hotwired/stimulus": "<%= asset_path('stimulus.min.js') %>",
+        "mailbox_gem/application": "<%= asset_path('mailbox_gem/application.js') %>",
+        "mailbox_gem/controllers/auto_refresh_controller": "<%= asset_path('mailbox_gem/controllers/auto_refresh_controller.js') %>"
+      }
+    }
+  </script>
+  <script type="module">import "mailbox_gem/application"</script>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/mailbox_gem/messages/_message_row.html.erb

@@ -0,0 +1,6 @@
+<tr>
+  <td><%= link_to message.from, message_path(message.id) %></td>
+  <td><%= message.to %></td>
+  <td><%= link_to message.subject.presence || "(no subject)", message_path(message.id) %></td>
+  <td><%= message.captured_at.strftime("%d %B, %Y, %I:%M %p") %></td>
+</tr>

data/app/views/mailbox_gem/messages/_search.html.erb

@@ -0,0 +1,34 @@
+<%= form_with url: messages_path,
+  method: :get,
+  class: "search-form",
+  data: { action: "submit->auto-refresh#submit" } do |f| %>
+
+  <div class="search-input-wrapper">
+    <div class="search-icon">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke-width="1.5"
+        stroke="currentColor"
+        class="size-6"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z"
+        />
+      </svg>
+    </div>
+    <%= f.search_field :q,
+                   value: query,
+                   placeholder: "Search from, to, subject…",
+                   class: "search-input",
+                   data: {
+                     auto_refresh_target: "search",
+                     action: "input->auto-refresh#search",
+                   } %>
+
+  </div>
+
+<% end %>

data/app/views/mailbox_gem/messages/_table.html.erb

@@ -0,0 +1,25 @@
+<% if messages.any? %>
+  <%= button_to "Clear all", clear_messages_path, method: :delete, class: "clear-button" %>
+
+  <table class="messages">
+    <thead>
+      <tr>
+        <th>From</th>
+        <th>To</th>
+        <th>Subject</th>
+        <th>Captured</th>
+      </tr>
+    </thead>
+    <tbody>
+      <%= render partial: "message_row", collection: messages, as: :message %>
+    </tbody>
+  </table>
+<% elsif query.present? %>
+  <p class="empty-state">No mail matches "<%= query %>".</p>
+<% else %>
+  <p class="empty-state">
+    No mail captured yet. Set
+    <code>config.action_mailer.delivery_method = :mailbox_gem</code>
+    in your development environment, then send some mail.
+  </p>
+<% end %>

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

@@ -0,0 +1,14 @@
+<div
+  data-controller="auto-refresh"
+  data-auto-refresh-base-url-value="<%= table_messages_path %>"
+  data-auto-refresh-query-value="<%= @query %>"
+>
+  <header class="mailbox-header">
+    <h1>Mailbox</h1>
+    <%= render "search", query: @query %>
+  </header>
+
+  <div data-auto-refresh-target="results">
+    <%= render "table", messages: @messages, query: @query %>
+  </div>
+</div>

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

@@ -0,0 +1,57 @@
+<%= link_to "← Back to mailbox", messages_path, class: "back-link" %>
+
+<h1><%= @message.subject.presence || "(no subject)" %></h1>
+
+<dl class="headers">
+  <dt>From</dt><dd><%= @message.from %></dd>
+  <dt>To</dt><dd><%= @message.to %></dd>
+  <% if @message.cc.present? %>
+    <dt>Cc</dt><dd><%= @message.cc %></dd>
+  <% end %>
+  <% if @message.bcc.present? %>
+    <dt>Bcc</dt><dd><%= @message.bcc %></dd>
+  <% end %>
+  <dt>Captured</dt><dd><%= @message.captured_at.strftime("%d %B, %Y, %I:%M %p") %></dd>
+</dl>
+
+<nav class="tabs">
+  <% if @message.html_body %>
+    <%= link_to "HTML",
+    message_path(@message.id, view: "html"),
+    class: ["tab", ("active" if @view == "html")] %>
+  <% end %>
+  <% if @message.text_body %>
+    <%= link_to "Text",
+    message_path(@message.id, view: "text"),
+    class: ["tab", ("active" if @view == "text")] %>
+  <% end %>
+  <%= link_to "Source",
+  message_path(@message.id, view: "source"),
+  class: ["tab", ("active" if @view == "source")] %>
+</nav>
+
+<% case @view %>
+<% when "html" %>
+    <iframe
+      class="body-frame"
+      sandbox=""
+      title="HTML body"
+      referrerpolicy="no-referrer"
+      srcdoc="<%= @message.html_body %>"
+    >
+    </iframe>
+  <% when "text" %>
+    <pre class="body-text"><%= @message.text_body %></pre>
+  <% when "source" %>
+    <pre class="body-text"><%= @message.source %></pre>
+  <% end %>
+
+  <% if @message.attachments.any? %>
+    <h2>Attachments</h2>
+    <ul class="attachments">
+      <% @message.attachments.each do |attachment| %>
+        <li><%= attachment.filename %>
+          <span class="muted">(<%= number_to_human_size(attachment.decoded.bytesize) %>)</span></li>
+      <% end %>
+    </ul>
+  <% end %>

data/config/routes.rb

@@ -0,0 +1,10 @@
+MailboxGem::Engine.routes.draw do
+  root to: "messages#index"
+
+  resources :messages, only: [ :index, :show ] do
+    collection do
+      get :table
+    end
+  end
+  delete "messages", to: "messages#clear", as: :clear_messages
+end

data/lib/mailbox_gem/delivery_method.rb

@@ -0,0 +1,22 @@
+module MailboxGem
+  # A Mail delivery method, in the same sense that Mail::SMTP or
+  # Mail::TestMailer are: something Mail::Message#deliver! can call
+  # #deliver!(self) on. Registered with ActionMailer::Base.add_delivery_method
+  # so a host app opts in with one config line, exactly like letter_opener or
+  # mailcatcher-rails do - not auto-enabled, since silently intercepting a
+  # host app's mail delivery without consent would break setups that already
+  # capture mail another way.
+  #
+  # This intentionally does not send anything, the same way Swoosh's local
+  # adapter or Mail::TestMailer don't: capturing dev mail should not depend
+  # on network access or a running SMTP relay.
+  class DeliveryMethod
+    def initialize(settings)
+      @settings = settings
+    end
+
+    def deliver!(mail)
+      Store.add(mail)
+    end
+  end
+end

data/lib/mailbox_gem/engine.rb

@@ -0,0 +1,15 @@
+module MailboxGem
+  class Engine < ::Rails::Engine
+    isolate_namespace MailboxGem
+
+    # ActiveSupport.on_load(:action_mailer) defers this until ActionMailer::Base
+    # is actually loaded, instead of referencing the constant at boot (which
+    # would force-load Action Mailer early and break eager_load ordering).
+    # This is the same hook premailer-rails and other mailer-extending gems use.
+    initializer "mailbox_gem.delivery_method" do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :mailbox_gem, MailboxGem::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/mailbox_gem/message.rb

@@ -0,0 +1,74 @@
+require "securerandom"
+
+module MailboxGem
+  # Wraps a Mail::Message captured off the delivery path.
+  #
+  # We wrap rather than expose Mail::Message directly so the controller/views
+  # depend on a small, stable interface instead of the mail gem's API -
+  # html_part/text_part branching on multipart? lives here, once, not in ERB.
+  class Message
+    attr_reader :id, :captured_at, :mail
+
+    def initialize(mail)
+      @id = SecureRandom.uuid
+      # Time.now, not Time.current: Time.current follows the host app's
+      # Time.zone (UTC by default in Rails), which has nothing to do with
+      # what a developer watching their own dev server actually wants here -
+      # their own machine's clock. Time.now always reads the OS's local zone.
+      @captured_at = Time.now
+      @mail = mail
+    end
+
+    def subject
+      mail.subject
+    end
+
+    def from
+      Array(mail.from).join(", ")
+    end
+
+    def to
+      Array(mail.to).join(", ")
+    end
+
+    def cc
+      Array(mail.cc).join(", ")
+    end
+
+    def bcc
+      Array(mail.bcc).join(", ")
+    end
+
+    def html_body
+      if mail.multipart?
+        mail.html_part&.decoded
+      elsif mail.mime_type == "text/html"
+        mail.body.decoded
+      end
+    end
+
+    def text_body
+      if mail.multipart?
+        mail.text_part&.decoded
+      elsif mail.mime_type.nil? || mail.mime_type == "text/plain"
+        mail.body.decoded
+      end
+    end
+
+    def attachments
+      mail.attachments
+    end
+
+    def source
+      mail.to_s
+    end
+
+    # Plain substring match, not a query language - the fields searched are
+    # exactly the ones shown in the index table, so results stay predictable.
+    def matches?(query)
+      return true if query.blank?
+
+      [ subject, from, to ].any? { |field| field.to_s.downcase.include?(query.downcase) }
+    end
+  end
+end

data/lib/mailbox_gem/store.rb

@@ -0,0 +1,58 @@
+module MailboxGem
+  # In-memory, thread-safe capture buffer.
+  #
+  # Deliberately not ActiveRecord-backed: this is a dev-only tool, and
+  # requiring a migration to install it would violate the "drop the gem in
+  # and go" experience we're after. The tradeoff, same one ActionMailer::Base
+  # .deliveries makes, is that the mailbox is wiped on process restart -
+  # acceptable for a tool whose job is to show you what *this* dev session
+  # sent.
+  #
+  # Puma's default dev config runs multiple threads, and Mail::Message#deliver!
+  # can be called concurrently across requests, so writes are Mutex-guarded.
+  #
+  # This only protects against races between threads in one process. It does
+  # NOT work across Puma worker processes (WEB_CONCURRENCY > 1) - each worker
+  # forks its own heap, so each gets its own independent Store, and the
+  # mailbox UI would silently show only whatever a given worker happened to
+  # capture. Unsupported for now: WEB_CONCURRENCY defaults to 1 (no cluster
+  # mode) in a standard Rails dev setup, and going cross-process-safe would
+  # mean file or DB-backed storage, a real cost for what's meant to stay a
+  # zero-config dev tool.
+  class Store
+    class << self
+      def add(mail)
+        message = Message.new(mail)
+
+        mutex.synchronize do
+          messages.unshift(message)
+          messages.pop while messages.size > MailboxGem.max_messages
+        end
+
+        message
+      end
+
+      def all
+        mutex.synchronize { messages.dup }
+      end
+
+      def find(id)
+        mutex.synchronize { messages.find { |message| message.id == id } }
+      end
+
+      def clear
+        mutex.synchronize { messages.clear }
+      end
+
+      private
+
+      def messages
+        @messages ||= []
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/mailbox_gem/version.rb

@@ -0,0 +1,3 @@
+module MailboxGem
+  VERSION = "0.1.0"
+end

data/lib/mailbox_gem.rb

@@ -0,0 +1,20 @@
+require "active_support/core_ext/module/attribute_accessors"
+
+# Bundler.require only requires gems listed directly in the host app's
+# Gemfile, not our own gemspec's runtime dependencies - so stimulus-rails'
+# Stimulus::Engine would never be defined, and Rails would never load its
+# vendored stimulus.min.js asset, unless we require it ourselves here.
+require "stimulus-rails"
+
+require "mailbox_gem/version"
+require "mailbox_gem/message"
+require "mailbox_gem/store"
+require "mailbox_gem/delivery_method"
+require "mailbox_gem/engine"
+
+module MailboxGem
+  # Maximum number of captured messages to retain. Oldest are dropped once
+  # this is exceeded - see Store#add. Override in an initializer:
+  #   MailboxGem.max_messages = 500
+  mattr_accessor :max_messages, default: 200
+end

data/lib/tasks/mailbox_gem_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :mailbox_gem do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: mailbox_gem
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Luka Tchelidze
+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: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Captures mail your app actually sends in development - through its real
+  Action Mailer delivery path, not a hand-written preview - and shows it in a live,
+  searchable inbox in the browser.
+email:
+- lukachelidze3008@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/assets/javascripts/mailbox_gem/application.js
+- app/assets/javascripts/mailbox_gem/controllers/auto_refresh_controller.js
+- app/assets/stylesheets/mailbox_gem/application.css
+- app/controllers/mailbox_gem/application_controller.rb
+- app/controllers/mailbox_gem/messages_controller.rb
+- app/helpers/mailbox_gem/application_helper.rb
+- app/jobs/mailbox_gem/application_job.rb
+- app/mailers/mailbox_gem/application_mailer.rb
+- app/models/mailbox_gem/application_record.rb
+- app/views/layouts/mailbox_gem/application.html.erb
+- app/views/mailbox_gem/messages/_message_row.html.erb
+- app/views/mailbox_gem/messages/_search.html.erb
+- app/views/mailbox_gem/messages/_table.html.erb
+- app/views/mailbox_gem/messages/index.html.erb
+- app/views/mailbox_gem/messages/show.html.erb
+- config/routes.rb
+- lib/mailbox_gem.rb
+- lib/mailbox_gem/delivery_method.rb
+- lib/mailbox_gem/engine.rb
+- lib/mailbox_gem/message.rb
+- lib/mailbox_gem/store.rb
+- lib/mailbox_gem/version.rb
+- lib/tasks/mailbox_gem_tasks.rake
+homepage: https://github.com/Null-logic-0/mailbox_gem
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Null-logic-0/mailbox_gem
+  source_code_uri: https://github.com/Null-logic-0/mailbox_gem
+  changelog_uri: https://github.com/Null-logic-0/mailbox_gem/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Null-logic-0/mailbox_gem/issues
+  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: 4.0.3
+specification_version: 4
+summary: A development-only email inbox for Rails, inspired by Phoenix's /dev/mailbox.
+test_files: []