rails_mail 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f203c591ad81cc5cc52b5aa4b9f88f7ba4cb54bda733f7f67650229cf5e4dc73
+  data.tar.gz: 6522e79faa67890b74d33a1a0529085627dbd0630d028b461e6af78143e80be5
+SHA512:
+  metadata.gz: 385b93bbbed99ad5f1909ddc87b3fdfccc7e4563d810c912bff197a9780abd62c07bbec4d426a30a3ce7967a5f5894e85b3236018d5e9ebafb9a065b28a38e90
+  data.tar.gz: 0da762085610c6dc626763b1610133fd826e915e15a20d329c924bc301763f969b0f6457b470fab597953ff368dbb964ff044f82873487e6250b03c90031148b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Peter Philips
+
+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,170 @@
+# RailsMail
+RailsMail is a Rails engine that provides a database-backed delivery method for Action Mailer, primarily intended for local development and staging environments. It captures emails sent through your Rails application and provides a web interface to view them.
+
+RailsMail saves all outgoing emails to your database instead of actually sending them. This is particularly useful for:
+- Local development to inspect emails without setting up a real mail server
+- Staging environments where you want to prevent actual email delivery
+- Testing email templates and layouts
+
+![rails mail screenshot](rails-mail-demo.png)
+
+### Features
+* Implements delivery_method for ActionMailer to catch emails and store them in the database
+* Real-time updates using Turbo and ActionCable
+* Search functionality across email fields (subject, from, to, cc, bcc)
+* Clean, responsive UI for viewing email contents
+* Optional authentication support
+* Trimming emails older than a specified duration or a maximum number of emails
+* Ability to manually clear emails out and turn on/off that functionality based on environment (eg, so that in Staging, other stakeholders can't clear emails out, but in dev sometimes you want a clean slate)
+* Dynamic time ago in words using date-fns
+
+## Installation
+
+To install RailsMail, follow these steps:
+
+1. **Add the gem to your application's Gemfile:**
+
+   ```ruby
+   gem "rails_mail"
+   ```
+
+2. **Run `bundle install` to install the gem:**
+
+   ```bash
+   $ bundle install
+   ```
+
+3. **Generate the necessary database migration:**
+
+   Run the following command to create the migration for storing emails:
+
+   ```bash
+   $ rake rails_mail:install:migrations
+   ```
+
+4. **Run the migration:**
+
+   Apply the migration to your database:
+
+   ```bash
+   $ rails db:migrate
+   ```
+
+5. **Start your Rails server and access the RailsMail interface:**
+
+   Visit `http://localhost:3000/rails_mail` to view captured emails.
+
+
+## Usage
+
+To use RailsMail in your application:
+
+1. **Configure Action Mailer to use RailsMail as the delivery method:**
+
+   Add the following configuration to your `config/environments/development.rb` (or `staging.rb`):
+
+   ```ruby
+   config.action_mailer.delivery_method = :rails_mail
+   ```
+
+2. **Mount the engine in your routes:**
+
+   Add the following line to your `config/routes.rb`:
+
+   ```ruby
+   mount RailsMail::Engine => "/rails_mail"
+   ```
+
+3. **Configure the initializer**
+   See the [Configuration](#configuration) section for more details.
+
+4. **Visit `/rails_mail` in your browser to view all captured emails.**
+
+### Configuration
+
+RailsMail can be configured through an initializer:
+
+```ruby
+# config/initializers/rails_mail.rb
+RailsMail.configure do |config|
+  # Optional authentication callback
+  # (if using Authlogic. If using Devise see the Authentication section)
+  config.authentication_callback do
+    user_session = UserSession.find
+    raise ActionController::RoutingError.new('Not Found') unless user_session&.user&.admin?
+  end
+
+  # Delete emails older than the specified duration
+  config.trim_emails_older_than = 30.days
+
+  # Keep only the most recent N emails
+  config.trim_emails_max_count = 1000
+
+  # Control whether trimming runs synchronously (:now) or asynchronously (:later)
+  config.sync_via = :later
+end
+```
+
+### Configuration Options
+
+- `authentication_callback`: A block that will be called before accessing RailsMail routes
+- `trim_emails_older_than`: Accepts an ActiveSupport::Duration object (e.g., 30.days). Emails older than this duration will be deleted.
+- `trim_emails_max_count`: Keeps only the N most recent emails, deleting older ones.
+- `sync_via`: Controls whether the trimming job runs synchronously (:now) or asynchronously (:later)
+
+## Authentication
+Authentication is optional, but recommended and will depend on your application's authentication setup. This gem provides an `authentication_callback` that you can configure in the initializer which is helpful for Authlogic. If you are using Devise, you can simply wrap the mount point of the engine. 
+
+### Authlogic
+
+If you're using Authlogic, configure the authentication in the initializer:
+```ruby
+# config/initializers/rails_mail.rb
+RailsMail.configure do |config|
+    config.authentication_callback do
+      user_session = UserSession.find
+      # Provide a more helpful message in development
+      msg = Rails.env.development? ? 'Forbidden - make sure you have the correct permission in config/initializers/rails_mail.rb' : 'Not Found'
+      raise ActionController::RoutingError.new(msg) unless user_session&.user&.admin?
+    end
+  end
+end
+```
+
+### Devise
+
+If you're using Devise, you can simply wrap the mount point of the engine using Devise's `authenticate` route helper.
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(user) { user.admin? } do
+    mount RailsMail::Engine => "/rails_mail"
+end
+```
+
+## Real-time updates
+
+RailsMail uses Turbo, TurboStreams, and ActionCable to provide real-time updates in the ui when emails are delivered. When you send an email, the new email will be displayed in the list of emails. There may be gotchas depending on your setup and environment.
+
+## Gotchas
+
+- In development environment, the typical default for ActionCable (cable.yml) is to use the async adapter which is an in-memory adapter. If you try to send an email from the rails console, it will not auto-update the ui. You can change the adapter to the development adapter by running `cable.yml` to use something like the redis, postgresql adapter, or solidcable. 
+- In staging environments, the same idea typically applies that you need to use a multi-process adapter like redis, postgresql, or solidcable.
+
+## Future work / ideas
+
+- Implement infinite scroll rather than loading all emails at once
+- Implement adapters to support real-time updates without ActionCable (polling or SSE)
+- Implement attachments support
+- Implement introspection of application notifiers and allow manual delivery/inspection of emails
+  - Need to introspect the arguments of the notifier and see if the arguments can be paired with active record models or to allow a mapping of argument type to sample data / fixtures. 
+- Implement read/unread functionality
+- Implement individual email delete
+- Implement multi-part (text/html) email support
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

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

data/app/channels/rails_mail/application_cable/channel.rb

@@ -0,0 +1,6 @@
+module RailsMail
+  module ApplicationCable
+    class Channel < ActionCable::Channel::Base
+    end
+  end
+end

data/app/channels/rails_mail/application_cable/connection.rb

@@ -0,0 +1,17 @@
+module RailsMail
+  module ApplicationCable
+    class Connection < ActionCable::Connection::Base
+      # identified_by :current_user
+
+      def connect
+        # self.current_user = find_verified_user
+      end
+
+      private
+
+      def find_verified_user
+        # TODO: Implement user verification
+      end
+    end
+  end
+end

data/app/channels/rails_mail/emails_channel.rb

@@ -0,0 +1,7 @@
+module RailsMail
+  class EmailsChannel < ApplicationCable::Channel
+    def subscribed
+      stream_from "rails_mail:emails"
+    end
+  end
+end

data/app/controllers/rails_mail/base_controller.rb

@@ -0,0 +1,13 @@
+module RailsMail
+  class BaseController < ActionController::Base
+    layout "rails_mail/application"
+    helper TurboHelper if defined?(TurboHelper)
+    before_action :authenticate!
+
+    private
+
+    def authenticate!
+      instance_eval(&RailsMail.authentication_callback) if RailsMail.authentication_callback.kind_of?(Proc)
+    end
+  end
+end

data/app/controllers/rails_mail/emails_controller.rb

@@ -0,0 +1,40 @@
+module RailsMail
+  class EmailsController < BaseController
+    # GET /emails
+    def index
+      @emails = Email.all
+      @emails = @emails.search(params[:q]) if params[:q].present?
+      @emails = @emails.order(created_at: :desc)
+      @email = params[:id] ? Email.find(params[:id]) : Email.last
+
+      respond_to do |format|
+        format.html
+        format.turbo_stream if params.key?(:q)
+      end
+    end
+
+    # GET /emails/1
+    def show
+      @emails = Email.order(created_at: :desc)
+      @email = Email.find(params[:id])
+      if request.headers["Turbo-Frame"]
+        render partial: "rails_mail/emails/show", locals: { email: @email }
+      else
+        render :index
+      end
+    end
+
+    def destroy_all
+      # Email.destroy_all
+      respond_to do |format|
+        format.html { redirect_to emails_path }
+        format.turbo_stream {
+          render turbo_stream: [
+            turbo_stream.update("email-sidebar", ""),
+            turbo_stream.update("email_content", partial: "empty_state")
+          ]
+        }
+      end
+    end
+  end
+end

data/app/controllers/rails_mail/frontends_controller.rb

@@ -0,0 +1,51 @@
+module RailsMail
+  class FrontendsController < ActionController::Base # rubocop:disable Rails/ApplicationController
+    STATIC_ASSETS = {
+      css: {
+        # tailwind: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "vendor", "tailwind", "tailwind.min.css"),
+        style: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "style.css")
+      },
+      js: {
+        tailwind: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "vendor", "tailwind", "tailwind.min.js")
+      }
+    }.freeze
+
+    # Additional JS modules that don't live in app/frontend/rails_mail/modules
+    MODULE_OVERRIDES = {
+      application: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "application.js"),
+      stimulus: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "vendor", "stimulus.js"),
+      turbo: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "vendor", "turbo.js"),
+      action_cable: RailsMail::Engine.root.join("app", "frontend", "rails_mail", "vendor", "action_cable.js"),
+      "date-fns": RailsMail::Engine.root.join("app", "frontend", "rails_mail", "vendor", "date-fns.js")
+    }.freeze
+
+    def self.js_modules
+      if Rails.env.production?
+        @_js_modules ||= load_js_modules
+      else
+        load_js_modules
+      end
+    end
+
+    def self.load_js_modules
+      RailsMail::Engine.root.join("app", "frontend", "rails_mail", "modules").children.select(&:file?).each_with_object({}) do |file, modules|
+        key = File.basename(file.basename.to_s, ".js").to_sym
+        modules[key] = file
+      end.merge(MODULE_OVERRIDES)
+    end
+
+    # Necessarly to serve Javascript to the browser
+    skip_after_action :verify_same_origin_request, raise: false
+    before_action { expires_in 1.year, public: true }
+
+    def static
+      render file: STATIC_ASSETS.dig(params[:format].to_sym, params[:name].to_sym) || raise(ActionController::RoutingError, "Not Found")
+    end
+
+    def module
+      raise(ActionController::RoutingError, "Not Found") if params[:format] != "js"
+
+      render file: self.class.js_modules[params[:name].to_sym] || raise(ActionController::RoutingError, "Not Found")
+    end
+  end
+end

data/app/frontend/rails_mail/application.js

@@ -0,0 +1,15 @@
+import { Application } from "stimulus";
+import "turbo";
+import EmailHighlightController from "email_highlight_controller";
+import AutoSubmit from 'auto_submit'
+import Timeago from 'timeago'
+
+const application = Application.start();
+
+application.register("email-highlight", EmailHighlightController);
+application.register('auto-submit', AutoSubmit)
+application.register('timeago', Timeago)
+
+window.Stimulus = Application.start();
+
+import "emails_channel";

data/app/frontend/rails_mail/modules/auto_submit.js

@@ -0,0 +1,30 @@
+import { Controller } from "stimulus";
+function debounce(callback, delay) {
+  let timeout;
+  return (...args) => {
+    clearTimeout(timeout), timeout = setTimeout(() => {
+      callback.apply(this, args);
+    }, delay);
+  };
+}
+const _AutoSubmit = class _AutoSubmit extends Controller {
+  initialize() {
+    this.submit = this.submit.bind(this);
+  }
+  connect() {
+    this.delayValue > 0 && (this.submit = debounce(this.submit, this.delayValue));
+  }
+  submit() {
+    this.element.requestSubmit();
+  }
+};
+_AutoSubmit.values = {
+  delay: {
+    type: Number,
+    default: 150
+  }
+};
+let AutoSubmit = _AutoSubmit;
+export {
+  AutoSubmit as default
+};

data/app/frontend/rails_mail/modules/consumer.js

@@ -0,0 +1,3 @@
+import { createConsumer } from "action_cable"
+
+export default createConsumer()

data/app/frontend/rails_mail/modules/email_highlight_controller.js

@@ -0,0 +1,48 @@
+import { Controller } from "stimulus"
+
+export default class extends Controller {
+  static targets = ["link"]
+  
+  // Define the Tailwind class as a static property
+  static activeClass = "bg-gray-100"
+
+  connect() {
+    console.log("EmailHighlightController connected")
+    // Listen for Turbo frame load events
+    document.addEventListener("turbo:frame-load", this.highlightCurrentEmail.bind(this))
+  }
+
+  disconnect() {
+    // Clean up event listener when the controller is disconnected
+    document.removeEventListener("turbo:frame-load", this.highlightCurrentEmail.bind(this))
+  }
+
+  // Called when a link is clicked
+  highlight(event) {
+    // Remove active class from all links
+    this.linkTargets.forEach(link => {
+      link.classList.remove(this.constructor.activeClass)
+    })
+
+    // Add active class to clicked link
+    const clickedLink = event.currentTarget
+    clickedLink.classList.add(this.constructor.activeClass)
+  }
+
+  highlightCurrentEmail() {
+    // Get the current email ID from the content frame
+    const emailContent = document.querySelector("#email_content [data-email-id]")
+    if (emailContent) {
+      const currentEmailId = emailContent.dataset.emailId
+
+      // Highlight the link with the matching email ID
+      this.linkTargets.forEach(link => {
+        if (link.dataset.emailId === currentEmailId) {
+          link.classList.add(this.constructor.activeClass)
+        } else {
+          link.classList.remove(this.constructor.activeClass)
+        }
+      })
+    }
+  }
+} 

data/app/frontend/rails_mail/modules/emails_channel.js

@@ -0,0 +1,12 @@
+import consumer from "consumer"    // Your Action Cable consumer setup
+import { renderStreamMessage } from "turbo" // If you've got turbo.js available
+
+consumer.subscriptions.create({
+  channel: "RailsMail::EmailsChannel"
+}, {
+  received(data) {
+    console.log("received data on Emails Channel", data)
+    // data should be a string containing <turbo-stream> tags
+    renderStreamMessage(data)
+  }
+})

data/app/frontend/rails_mail/modules/timeago.js

@@ -0,0 +1,41 @@
+import { Controller } from "stimulus";
+import { formatDistanceToNow } from "date-fns";
+const _Timeago = class _Timeago extends Controller {
+  initialize() {
+    this.isValid = !0;
+  }
+  connect() {
+    this.load(), this.hasRefreshIntervalValue && this.isValid && this.startRefreshing();
+  }
+  disconnect() {
+    this.stopRefreshing();
+  }
+  load() {
+    const datetime = this.datetimeValue, date = Date.parse(datetime), options = {
+      includeSeconds: this.includeSecondsValue,
+      addSuffix: this.addSuffixValue,
+      locale: this.locale
+    };
+    Number.isNaN(date) && (this.isValid = !1, console.error(
+      `[@stimulus-components/timeago] Value given in 'data-timeago-datetime' is not a valid date (${datetime}). Please provide a ISO 8601 compatible datetime string. Displaying given value instead.`
+    )), this.element.dateTime = datetime, this.element.innerHTML = this.isValid ? formatDistanceToNow(date, options) : datetime;
+  }
+  startRefreshing() {
+    this.refreshTimer = setInterval(() => {
+      this.load();
+    }, this.refreshIntervalValue);
+  }
+  stopRefreshing() {
+    this.refreshTimer && clearInterval(this.refreshTimer);
+  }
+};
+_Timeago.values = {
+  datetime: String,
+  refreshInterval: Number,
+  includeSeconds: Boolean,
+  addSuffix: Boolean
+};
+let Timeago = _Timeago;
+export {
+  Timeago as default
+};