outbound_mailbox 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2593221e73c6c30a39d3bf5823ab1daff84827965f17352ef4970ff44ad6609b
+  data.tar.gz: f2b88374df3d4e60c348ea100b56a09aa284764af41d1854588ee29a7062e6ec
+SHA512:
+  metadata.gz: fd2758390597ed5b28ddb4508fcddab6b7814b099e901c04dd053f88583765784952d7de9c241c821b38cee03b6b0bc1dc83f1111c5bbdb6b8fcd0c84a5ff240
+  data.tar.gz: '04084ae34c19dfafcd23691c8fe8ade5611ec8eab93e10d8c97c436b13d34bda1be67be7af5ccad87afd514f390fa7111a2e3393421ae24b681dc45782c1f6b1'

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) Ackama
+
+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,86 @@
+# Outbound Mailbox
+
+Rails engine that stores **outbound** email the same way [Action Mailbox](https://guides.rubyonrails.org/action_mailbox_basics.html) stores **inbound** email: Active Record metadata, raw RFC822 source in Active Storage, a Mail delivery method, and an HTML conductor at `/rails/conductor/outbound_mailbox/outbound_emails` when enabled — by default if Action Mailer uses `delivery_method :outbound_mailbox`, or any time via `config.outbound_mailbox.mount_conductor`.
+
+There is **no runtime dependency on Action Mailer** in the library; the delivery class implements Mail’s delivery contract so any stack that ends in `Mail::Message#deliver!` can use it. Typical Rails hosts configure Action Mailer to use this method in development.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "outbound_mailbox"
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails generate outbound_mailbox:install
+bin/rails db:migrate
+```
+
+Optional: use a dedicated Active Storage service for captured mail (mirrors Action Mailbox’s `config.action_mailbox.storage_service`):
+
+```ruby
+# config/application.rb
+config.outbound_mailbox.storage_service = :local # or any configured service name
+```
+
+To browse captured mail via the conductor without using Action Mailer's `:outbound_mailbox` delivery method (for example you call `OutboundMailbox::OutboundEmail.create_from_mail!` yourself or use a custom delivery path), enable routes explicitly:
+
+```ruby
+# config/application.rb
+config.outbound_mailbox.mount_conductor = true
+```
+
+Set to `false` to hide the conductor even when `delivery_method` is `:outbound_mailbox`. You can also assign a proc: `config.outbound_mailbox.mount_conductor = ->(app) { ... }` (must return a boolean-coercible value). The default is `nil`, meaning mount when `config.action_mailer.delivery_method` is `:outbound_mailbox`.
+
+## Capturing mail in development
+
+```ruby
+# config/environments/development.rb
+config.action_mailer.delivery_method = :outbound_mailbox
+```
+
+This replaces real SMTP delivery in that environment (similar to `:test` or Letter Opener). Plain `Mail` is also supported if you assign the same delivery class.
+
+## Conductor
+
+By default, when `config.action_mailer.delivery_method` is **`:outbound_mailbox`**, the engine registers conductor routes under:
+
+`/rails/conductor/outbound_mailbox/outbound_emails`
+
+You can override that with `config.outbound_mailbox.mount_conductor`; see **Installation** optional settings above.
+
+List and show stored messages, or **Incinerate** to delete a record and purge its blob. When routes are not registered, those URLs are not routed (**404**). Route registration follows `config/routes.rb` (startup and reload in development).
+
+
+## Testing this gem
+
+Tests boot a **single-file** Rails app in [`test/dummy/app.rb`](test/dummy/app.rb). Migrations live under [`test/dummy/db/migrate`](test/dummy/db/migrate).
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+Continuous integration uses the **latest stable MRI Ruby** [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby), `ruby-version: "ruby"` and exercises **Rails 8.1** (default `Gemfile`), **Rails 8.0**, **Rails 7.1**, and **Rails 7.0** via [`gemfiles/rails_8_1.gemfile`](gemfiles/rails_8_1.gemfile), [`gemfiles/rails_8_0.gemfile`](gemfiles/rails_8_0.gemfile), [`gemfiles/rails_7_1.gemfile`](gemfiles/rails_7_1.gemfile), and [`gemfiles/rails_7_0.gemfile`](gemfiles/rails_7_0.gemfile). To match a matrix entry locally:
+
+```bash
+BUNDLE_GEMFILE=gemfiles/rails_7_0.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7_0.gemfile bundle exec rake test
+```
+
+The gem’s **Gemfile** includes `actionmailer` so `config.action_mailer` exists in that app; the **gemspec** does not list `action_mailer` or `actionmailbox` as runtime dependencies. Runtime Rails components are constrained to **`>= 7.0`, `< 8.2`** (`actionpack`, `activestorage`, `activerecord`, `railties`). The gem requires **Ruby 3.1+** (`required_ruby_version`).
+
+## Releasing
+
+Releases are done automatically by GitHub Actions when a new tag is pushed to the repository.
+
+To release a new version, create a pull request updating the "Unreleased" section of `CHANGELOG.md` file to reflect the upcoming version and expected release date, and to update the version number in `lib/outbound_mailbox/version.rb`. Once the pull request is merged, create a new tag in the format `vX.Y.Z`, which will trigger GitHub Actions to publish the new version to RubyGems.
+
+## License
+
+MIT — see [MIT-LICENSE](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/rails/conductor/outbound_mailbox/outbound_emails_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rails
+  module Conductor
+    module OutboundMailbox
+      class OutboundEmailsController < ActionController::Base
+        layout "outbound_mailbox/conductor"
+
+        def index
+          @outbound_emails = ::OutboundMailbox::OutboundEmail.order(created_at: :desc)
+        end
+
+        def show
+          @outbound_email = ::OutboundMailbox::OutboundEmail.find(params[:id])
+        end
+
+        def destroy
+          @outbound_email = ::OutboundMailbox::OutboundEmail.find(params[:id])
+          @outbound_email.incinerate
+          redirect_to rails_conductor_outbound_mailbox_outbound_emails_path, notice: "Email incinerated"
+        end
+      end
+    end
+  end
+end

data/app/models/outbound_mailbox/outbound_email.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "mail"
+require "openssl"
+require "stringio"
+
+module OutboundMailbox
+  # Persists the raw RFC822 source in Active Storage (metadata is a checksum only; outbound mail does not need RFC Message-ID for deduplication).
+  class OutboundEmail < Record
+    has_one_attached :raw_email
+
+    class << self
+      def create_from_mail!(mail)
+        source = mail.encoded
+        checksum = OpenSSL::Digest::SHA1.hexdigest(source)
+        create!(
+          raw_email: create_and_upload_raw_blob!(source),
+          message_checksum: checksum
+        )
+      end
+
+      private
+
+      def create_and_upload_raw_blob!(source)
+        args = {
+          io: StringIO.new(source),
+          filename: "message.eml",
+          content_type: "message/rfc822"
+        }
+        args[:service_name] = OutboundMailbox.storage_service if OutboundMailbox.storage_service.present?
+        ActiveStorage::Blob.create_and_upload!(**args)
+      end
+    end
+
+    def mail
+      @mail ||= OutboundMailbox.mail_message_from_raw_source(source)
+    end
+
+    def source
+      @source ||= raw_email.download
+    end
+
+    def incinerate
+      transaction do
+        raw_email.purge if raw_email.attached?
+        destroy!
+      end
+    end
+  end
+end

data/app/models/outbound_mailbox/record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OutboundMailbox
+  class Record < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/outbound_mailbox/conductor.html.erb

@@ -0,0 +1,8 @@
+<html>
+<head>
+  <title>Rails Conductor: <%= yield :title %></title>
+</head>
+<body>
+<%= yield %>
+</body>
+</html>

data/app/views/rails/conductor/outbound_mailbox/outbound_emails/index.html.erb

@@ -0,0 +1,24 @@
+<h1>Outbound emails</h1>
+
+<table>
+  <thead>
+    <tr>
+      <th>ID</th>
+      <th>Subject</th>
+      <th>Checksum</th>
+      <th>Created</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @outbound_emails.each do |email| %>
+      <tr>
+        <td><%= email.id %></td>
+        <td><%= email.mail.subject %></td>
+        <td><code><%= email.message_checksum.slice(0, 12) %>…</code></td>
+        <td><%= email.created_at %></td>
+        <td><%= link_to "Show", rails_conductor_outbound_mailbox_outbound_email_path(email) %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/rails/conductor/outbound_mailbox/outbound_emails/show.html.erb

@@ -0,0 +1,19 @@
+<h1>Outbound email #<%= @outbound_email.id %></h1>
+
+<dl>
+  <dt>Checksum</dt>
+  <dd><code><%= @outbound_email.message_checksum %></code></dd>
+  <dt>Created</dt>
+  <dd><%= @outbound_email.created_at %></dd>
+</dl>
+
+<h2>Headers</h2>
+<pre><%= ERB::Util.html_escape(@outbound_email.mail.header.fields.map(&:to_s).join("\n")) %></pre>
+
+<h2>Raw source</h2>
+<pre><%= ERB::Util.html_escape(@outbound_email.source) %></pre>
+
+<p>
+  <%= link_to "Back to list", rails_conductor_outbound_mailbox_outbound_emails_path %>
+  <%= button_to "Incinerate", rails_conductor_outbound_mailbox_outbound_email_path(@outbound_email), method: :delete, form: { data: { turbo: false } } %>
+</p>

data/config/routes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  if OutboundMailbox.mount_conductor_routes?(Rails.application)
+    scope "rails/conductor/outbound_mailbox/", module: "rails/conductor/outbound_mailbox" do
+      resources :outbound_emails, only: %i[index show destroy], as: :rails_conductor_outbound_mailbox_outbound_emails
+    end
+  end
+end

data/lib/generators/outbound_mailbox/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record/migration"
+
+module OutboundMailbox
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Creates an Outbound Mailbox migration."
+
+    def copy_migration
+      migration_template "migration.rb", "db/migrate/create_outbound_mailbox_outbound_emails.rb"
+    end
+  end
+end

data/lib/generators/outbound_mailbox/templates/migration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class CreateOutboundMailboxOutboundEmails < ActiveRecord::Migration::Current
+  def change
+    create_table :outbound_mailbox_outbound_emails do |t|
+      t.string :message_checksum, null: false
+
+      t.timestamps
+    end
+
+    add_index :outbound_mailbox_outbound_emails, :created_at
+  end
+end

data/lib/outbound_mailbox/engine.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OutboundMailbox
+  class Engine < ::Rails::Engine
+    isolate_namespace OutboundMailbox
+
+    config.generators do |g|
+      g.test_framework :test_unit
+    end
+
+    config.outbound_mailbox = ActiveSupport::OrderedOptions.new
+    config.outbound_mailbox.storage_service = nil
+    # nil = derive from Action Mailer delivery_method (see OutboundMailbox.mount_conductor_routes?)
+    config.outbound_mailbox.mount_conductor = nil
+
+    initializer "outbound_mailbox.storage_service" do
+      config.after_initialize do |app|
+        OutboundMailbox.storage_service = app.config.outbound_mailbox.storage_service
+      end
+    end
+
+    initializer "outbound_mailbox.action_mailer" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method :outbound_mailbox, OutboundMailbox::MailDelivery
+      end
+    end
+  end
+end

data/lib/outbound_mailbox/mail_delivery.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OutboundMailbox
+  # Mail delivery handler (same contract as Mail::TestMailer).
+  # Register with Action Mailer via +config.action_mailer.delivery_method = :outbound_mailbox+.
+  class MailDelivery
+    attr_accessor :settings
+
+    def initialize(values = {})
+      @settings = (values || {}).dup
+    end
+
+    def deliver!(mail)
+      OutboundMailbox::OutboundEmail.create_from_mail!(mail)
+    end
+  end
+end

data/lib/outbound_mailbox/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OutboundMailbox
+  VERSION = "1.0.0"
+end

data/lib/outbound_mailbox.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "mail"
+require "outbound_mailbox/version"
+require "outbound_mailbox/engine"
+require "outbound_mailbox/mail_delivery"
+
+module OutboundMailbox
+  mattr_accessor :storage_service, default: nil
+
+  # True when +delivery_method+ is configured as +outbound_mailbox+ for Action Mailer.
+  # See also {.mount_conductor_routes?} for overriding via +config.outbound_mailbox.mount_conductor+.
+  def self.conductor_routes_enabled_for_delivery_method?(delivery_method)
+    delivery_method&.to_sym == :outbound_mailbox
+  end
+
+  # Whether conductor routes should be drawn (+config/routes.rb+).
+  #
+  # +config.outbound_mailbox.mount_conductor+ must be one of:
+  # * +nil+ (default) — mount only when {.conductor_routes_enabled_for_delivery_method?}
+  #   is true for +app.config.action_mailer.delivery_method+.
+  # * +true+ / +false+ — force conductor routes on or off (ignore delivery method). Use +true+
+  #   if you persist mail without setting Action Mailer to +:outbound_mailbox+ but still want the UI.
+  # * Anything responding to +call+ (+Proc+, method object, ...) — invoked as +callable.call(app)+;
+  #   the return value is coerced with +!!+ so use a boolean return for clarity.
+  def self.mount_conductor_routes?(app)
+    raw = app.config.outbound_mailbox.mount_conductor
+    case raw
+    when nil
+      conductor_routes_enabled_for_delivery_method?(app.config.action_mailer.delivery_method)
+    when true, false
+      raw
+    else
+      unless raw.respond_to?(:call)
+        raise ArgumentError, "config.outbound_mailbox.mount_conductor must be nil, true/false, or callable; got #{raw.class}"
+      end
+
+      !!raw.call(app)
+    end
+  end
+
+  # Same behavior as Action Mailbox’s +Mail.from_source+, without pulling in that gem.
+  def self.mail_message_from_raw_source(source)
+    Mail.new(Mail::Utilities.binary_unsafe_to_crlf(source.to_s))
+  end
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: outbound_mailbox
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ackama
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+description: Rails engine that stores outbound mail like Action Mailbox stores inbound
+  mail.
+email:
+- hello@ackama.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/rails/conductor/outbound_mailbox/outbound_emails_controller.rb
+- app/models/outbound_mailbox/outbound_email.rb
+- app/models/outbound_mailbox/record.rb
+- app/views/layouts/outbound_mailbox/conductor.html.erb
+- app/views/rails/conductor/outbound_mailbox/outbound_emails/index.html.erb
+- app/views/rails/conductor/outbound_mailbox/outbound_emails/show.html.erb
+- config/routes.rb
+- lib/generators/outbound_mailbox/install_generator.rb
+- lib/generators/outbound_mailbox/templates/migration.rb
+- lib/outbound_mailbox.rb
+- lib/outbound_mailbox/engine.rb
+- lib/outbound_mailbox/mail_delivery.rb
+- lib/outbound_mailbox/version.rb
+homepage: https://github.com/ackama/outbound_mailbox
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ackama/outbound_mailbox
+  source_code_uri: https://github.com/ackama/outbound_mailbox
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails engine that stores outbound mail like Action Mailbox stores inbound
+  mail.
+test_files: []