mail_delivery_task 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0d058a7ce383210d1d6769a0e59a3e43e606086a
+  data.tar.gz: 0ba26ba17147024483910e2836b5645a67a61ea8
+SHA512:
+  metadata.gz: b071d4dbf1ee7de728d02513cfb74530b581cc7a00a6884c07a1ac6e7110dbb9d2a9c673d8152e8246705ee7d70142c010ece9a08cf03db42838a14db491294c
+  data.tar.gz: c09934358f9a0541ec55ad986e6e53bbf362a8379047e31fac7d8d6b3991844d5ce06a6be2edcb64d81090f617020baa67a07719757820601eefb68cf395f8b6

data/.gitignore

@@ -0,0 +1,22 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Ignore all logfiles and tempfiles
+*.log
+*.swp
+
+# Ignore all sqlite3 files
+*.sqlite3
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,29 @@
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Security/YAMLLoad:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/CHANGES.md

@@ -0,0 +1,3 @@
+### 0.0.1 / 2018-1-22
+
+* Initial release

data/Gemfile

@@ -0,0 +1,22 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mail_delivery_task.gemspec
+gemspec
+
+# Core
+gem 'bundler', '~> 1.14'
+gem 'rake', '~> 11.0'
+
+# Development Experience
+gem 'pry'
+gem 'pry-byebug'
+gem 'rubocop'
+
+# Testing (see spec/dummy)
+gem 'factory_bot'
+gem 'rails', '~> 5.1.0'
+gem 'rspec', '~> 3.5'
+gem 'rspec-rails', '~> 3.0'
+gem 'sqlite3'
+
+gem 'timecop'

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2017 Square, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,283 @@
+# MailDeliveryTask
+
+[![Gem Version](https://badge.fury.io/rb/mail_delivery_task.svg)](http://badge.fury.io/rb/mail_delivery_task)
+[![License](https://img.shields.io/badge/license-Apache-green.svg?style=flat)](https://github.com/square/mail_delivery_task/blob/master/LICENSE)
+
+This gem provides generators and mixins to queue up mail delivery in database transactions to be
+delivered later. Doing so prevents mail from being sent twice if the transaction is rolled back:
+
+```ruby
+transaction do
+  model = MyModel.create!(foo: 'hello')
+  MyMailer.mailer_action(model: model).deliver
+  raise
+end
+```
+
+Despite database transaction rolling back the creation of the `MyModel` record, the mail is still
+delivered. This problem becomes more difficult in nested transactions. To avoid this, we create a
+a `MailDeliveryTask::Attempt` record inside the database. These records are then delivered at a
+later time using a job:
+
+```ruby
+transaction do
+  model = MyModel.create!(foo: 'hello')
+
+  # To be sent by a job later
+  MailDeliveryTask::Attempt.create(
+    mailer_class: MyMailer,
+    mailer_action_name: :mailer_action,
+    mailer_args: { my_model: model },
+    idempotence_token: "my_model##{id}"
+  )
+
+  raise
+end
+```
+
+The above pattern ensures mail delivery tasks will not be created nor sent when the transaction
+fails.
+
+The gem provides the following:
+
+* Models
+  * Generators for the `MailDeliveryTask::Attempt` migration, model, factory, and specs.
+  * Tracking completion using `completed_at`.
+  * Fields for `mailer_class_name`, `mailer_action_name`, and `mailer_args`.
+  * `MailDeliveryTask::BaseAttempt` mixin to provide model methods.
+  * Persistence token support.
+  * A `num_attempts` field gives you flexibility to handle retries and other failure scenarios.
+  * `status` and `completed_at` are fields that track state.
+* Jobs
+  * Generators for `MailDeliveryTaskJob` and `MailDeliveryBatchJob` jobs and specs
+  * `MailDeliveryTask::BaseDeliveryJob` and `MailDeliveryTask::BaseDeliveryBatchJob` mixins.
+
+## Design Motivations
+
+We're relying heavily on generators and mixins. Including the `MailDeliveryTask::BaseAttempt` module
+allows us to generate a model that can inherit from both `ActiveRecord::Base` (Rails 4) and
+`ApplicationRecord` (Rails 5). The `BaseAttempt` module's methods can easily be overridden, giving
+callers flexibility to handle errors, extend functionality, and inherit (STI). Lastly, the generated
+migrations provide fields used by the `BaseAttempt` module, but the developer is free to add their
+own fields and extend the module's methods while calling `super`.
+
+This gem is also designed to be compatible with any `ApplicationMailer` implementation through the
+use of the `mailer_class_name`, `mailer_action_name`, and `mailer_args` (keyword args) fields.
+
+## Getting Started
+
+1. Add the gem to your application's Gemfile and execute `bundle install` to install it:
+
+```ruby
+gem 'mail_delivery_task'
+```
+
+2. Generate migrations, base models, jobs, and specs. Feel free to add any additional columns you
+may need to the generated migration file:
+
+`$ rails generate mail_delivery_task:install`
+
+3. You will need a working `ActionMailer` class to send mail through SMTP / Butter. **Note: the
+mailer's arguments MUST be keyword arguments to be compatible with the `mailer_args` field in the
+`MailDeliveryTask` model.**
+
+```ruby
+class DummyMailer < ApplicationMailer
+  # Keyword args required!!!
+  def action_name(to_address:)
+    mail(
+      to: to_address,
+      subject: 'How to setup mail_delivery_task',
+      body: "It's really easy.",
+      content_type: 'text/plain',
+    )
+  end
+end
+```
+
+4. Rename the model and migrations as you see fit. Make sure your model contains
+`include MailDeliveryTask::BaseAttempt`.
+
+```ruby
+class MailDeliveryTask < ActiveRecord::Base
+  include MailDeliveryTask::BaseAttempt
+end
+```
+
+5. Implement the `handle_deliver_mail_error` and `handle_persist_mail_error` in your `MailDeliveryTask`
+model. These two methods are used by `MailDeliveryTask::BaseAttempt` when exceptions are thrown
+delivering and persisting the mail. See cookbook below for details on persistence and error
+handling.
+
+6. Do not send mail directly using the `ActionMailer` class above. Instead, create
+`MailDeliveryTask`s to be sent later by a job (generated) that includes a
+`MailDeliveryTask::BaseDeliveryJob`:
+
+```ruby
+class MailDeliveryJob < ActiveJob::Base
+  include MailDeliveryTask::BaseDeliveryJob
+end
+```
+
+```ruby
+transaction do
+  # Using the DummyMailer class above...
+  MailDeliveryTask::Attempt.create(
+    mailer_class: DummyMailer,
+    mailer_action_name: :action_name,
+    mailer_args: { to_address: 'jchang@squareup.com' },
+    idempotence_token: 'token',
+  )
+end
+```
+
+7. **Make sure to schedule the mail delivery job to run frequently using [`Clockwork`](https://github.com/adamwiggins/clockwork).**
+
+8. If you would like to use something other than Trunk to persist mail, see the cookbook below on
+using a different method of persistence.
+
+## Improper Uses of the Gem
+
+Below are patterns that defeat the purpose of using this gem:
+
+```ruby
+# DO NOT DO THIS
+transaction do
+  task = create_mail_delivery_task
+  task.deliver!
+  raise
+end
+```
+
+The above example allows mail to be delivered even if the transaction fails.
+
+```ruby
+# DO NOT DO THIS
+MailDeliverytask::Attempt.create(
+  mailer_class: 'DummyMailer',
+  mailer_action_name: 'action_name',
+  mailer_args: {},
+).deliver!
+```
+
+These two examples above do not make use of a job to deliver mail.
+
+## Cookbook
+
+### Delayed Execution
+
+Setting the `scheduled_at` field allows delayed execution to be possible. A task that has an
+`scheduled_at` before `Time.current` will be executed by `MailDeliveryTask::BaseDeliveryBatchJob`.
+
+### Overriding MailDeliveryTask::Base Error Handlers
+
+By default, when persistence or deliverance fails, it just raises the error
+encountered. However, if you want to raise a custom error or wrap the error,
+you can override both of these by overriding the `handle_deliver_mail_error`
+and `handle_persist_mail_error` methods.
+
+```ruby
+class MailDeliveryTask::Attempt < ApplicationRecord
+  include MailDeliveryTask::BaseAttempt
+
+  class DeliverMailError < StandardError; end
+  class PersistMailError < StandardError; end
+
+  def handle_deliver_mail_error(error)
+    raise DeliverMailError, 'my custom error message'
+  end
+
+  def handle_persist_mail_error(error)
+    raise PersistMailError, 'my custom error message'
+  end
+end
+```
+
+Lastly, the `num_attempts` field in `MailDeliveryTask::Attempt` allows you to track the number of
+delivery attempts the mail has. Use this to implement retries and permanent failure thresholds for
+your mail delivery tasks.
+
+### Proper Usage of `expire!` / `fail!`
+
+`expire!` should be used for mail that is no longer applicable, such as a mail for plan past due
+when the plan is no longer past due.
+
+`fail!` should be used to mark delivery as failed when the mail should have been, but was not,
+delivered successfully.
+
+### Persistence
+
+If you wish to persist mail, override the `persist_mail` method:
+
+```ruby
+class MailDeliveryTask::Attempt < ApplicationRecord
+  include MailDeliveryTask::BaseAttempt
+
+  private
+
+  def persist_mail(mail)
+    store_in_s3(mail.to_s)
+  end
+end
+```
+
+Don't forget to set the `persistence_token`.
+
+### Custom Matchers for RSpec
+
+Add the following lines to `rails_helper.rb`:
+
+```ruby
+require 'mail_delivery_task/testing'
+
+RSpec.configure do |config|
+  config.include MailDeliveryTask::Testing::MailerHelper, type: :mailer
+end
+```
+
+Now custom matchers like `be_deliverable` are enabled:
+
+```ruby
+expect(mail).to be_deliverable
+```
+
+For a full list of matchers, see [here](https://github.com/square/mail_delivery_task/tree/master/lib/mail_delivery_task/testing/mailer_helper.rb).
+
+### Overriding the Mail Delivery Mechanism
+
+Sometimes the mail delivery method found in the [BaseAttempt](https://github.com/square/mail_delivery_task/tree/master/lib/mail_delivery_task/base_attempt.rb) is insufficient. In this case you can override the method in your `MailDeliveryTask::Attempt`:
+
+```ruby
+class MailDeliveryTask::Attempt < ApplicationRecord
+  include MailDeliveryTask::BaseAttempt
+
+  private
+
+  def deliver_mail(mail)
+    mail.deliver_some_other_way
+  end
+end
+```
+
+## Development
+
+* Install dependencies with `bin/setup`.
+* Run tests/lints with `rake`
+* For an interactive prompt that will allow you to experiment, run `bin/console`.
+
+## License
+
+```
+Copyright 2017 Square, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require 'bundler/setup'
+require 'sq/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+require 'sq/lint/rake_task'
+Sq::Lint::RakeTask.new
+
+task default: %w(spec rubocop sq:lint:gem)

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "mail_delivery_task"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/mail_delivery_task/install_generator.rb

@@ -0,0 +1,37 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module MailDeliveryTask
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    source_root File.expand_path('../templates/', __FILE__)
+
+    desc 'Generates (but does not run) migrations to add the' \
+         ' mail_delivery_task_attempts table and creates the base model'
+
+    def self.next_migration_number(dirname)
+      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    def create_migration_file
+      migration_template 'create_mail_delivery_task_attempts.rb', 'db/migrate/create_mail_delivery_task_attempts.rb'
+    end
+
+    def create_mail_delivery_task_files
+      template 'mail_delivery_task_attempt.rb.erb', 'app/models/mail_delivery_task/attempt.rb'
+      template 'mail_delivery_job.rb.erb', 'app/jobs/mail_delivery_job.rb'
+      template 'mail_delivery_batch_job.rb.erb', 'app/jobs/mail_delivery_batch_job.rb'
+
+      if defined?(RSpec)
+        template 'mail_delivery_task_attempt_spec.rb.erb', 'spec/models/mail_delivery_task/attempt_spec.rb'
+        template 'mail_delivery_job_spec.rb.erb', 'spec/jobs/mail_delivery_job_spec.rb'
+        template 'mail_delivery_batch_job_spec.rb.erb', 'spec/jobs/mail_delivery_batch_job_spec.rb'
+      end
+
+      if defined?(FactoryBot) || defined?(FactoryGirl)
+        template 'mail_delivery_task_attempts.rb.erb', 'spec/factories/mail_delivery_task/attempts.rb'
+      end
+    end
+  end
+end

data/lib/generators/mail_delivery_task/templates/create_mail_delivery_task_attempts.rb

@@ -0,0 +1,39 @@
+class CreateMailDeliveryTaskAttempts < ActiveRecord::Migration[5.1]
+  def change
+    create_table :mail_delivery_task_attempts do |t|
+      t.integer       :lock_version, null: false, default: 0
+
+      t.string        :status
+      t.string        :idempotence_token, null: false
+
+      t.string        :mailer_class_name, null: false
+      t.string        :mailer_action_name, null: false
+      t.text          :mailer_args
+
+      t.boolean       :should_persist, default: false
+      t.string        :mailer_message_id
+      t.string        :persistence_token
+
+      t.integer       :num_attempts, null: false, default: 0
+
+      t.datetime      :scheduled_at
+      t.datetime      :completed_at
+
+      t.timestamps    null: false
+
+      t.index :status
+      t.index [:idempotence_token, :mailer_class_name, :mailer_action_name], unique: true, name: 'index_mdt_attempts_on_idempotence_token_and_mailer'
+
+      t.index [:mailer_class_name, :mailer_action_name], name: 'index_mdt_attempts_on_mailer_and_template'
+
+      t.index :should_persist
+      t.index :mailer_message_id
+
+      t.index :scheduled_at
+      t.index :completed_at
+
+      t.index :created_at
+      t.index :updated_at
+    end
+  end
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_batch_job.rb.erb

@@ -0,0 +1,3 @@
+class MailDeliveryBatchJob < <% if Rails::VERSION::STRING >= '5' %>ApplicationJob<% else %>ActiveJob::Base<% end %>
+  include MailDeliveryTask::BaseDeliveryBatchJob
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_batch_job_spec.rb.erb

@@ -0,0 +1,5 @@
+require 'rails_helper'
+
+RSpec.describe MailDeliveryBatchJob, type: :job do
+  pending "add some examples to (or delete) #{__FILE__}"
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_job.rb.erb

@@ -0,0 +1,3 @@
+class MailDeliveryJob < <% if Rails::VERSION::STRING >= '5' %>ApplicationJob<% else %>ActiveJob::Base<% end %>
+  include MailDeliveryTask::BaseDeliveryJob
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_job_spec.rb.erb

@@ -0,0 +1,5 @@
+require 'rails_helper'
+
+RSpec.describe MailDeliveryJob, type: :job do
+  pending "add some examples to (or delete) #{__FILE__}"
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_task_attempt.rb.erb

@@ -0,0 +1,24 @@
+class MailDeliveryTask::Attempt < <% if Rails::VERSION::STRING >= '5' %>ApplicationRecord<% else %>ActiveRecord::Base<% end %>
+  include MailDeliveryTask::BaseAttempt
+
+  # @override
+  #
+  # Override this method to deliver mail.
+  def persist_mail(mail)
+    raise NotImplementedError
+  end
+
+  # @override
+  #
+  # This method is used by MailDeliveryTask::BaseAttempt when #perform! fails.
+  def handle_deliver_mail_error(error)
+    raise error
+  end
+
+  # @override
+  #
+  # This method is used by MailDeliveryTask::BaseAttempt when #perform! fails.
+  def handle_persist_mail_error(error)
+    raise error
+  end
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_task_attempt_spec.rb.erb

@@ -0,0 +1,5 @@
+require 'rails_helper'
+
+RSpec.describe MailDeliveryTask::Attempt, type: :model do
+  pending "add some examples to (or delete) #{__FILE__}"
+end

data/lib/generators/mail_delivery_task/templates/mail_delivery_task_attempts.rb.erb

@@ -0,0 +1,27 @@
+<% if defined?(FactoryBot) %>FactoryBot<% else %>FactoryGirl<%end%>.define do
+  factory :mail_delivery_task_attempt, class: 'MailDeliveryTask::Attempt' do
+    status             { 'pending' }
+
+    idempotence_token  { SecureRandom.hex }
+
+    mailer_class_name  { 'DummyMailer' }
+    mailer_action_name { 'action_name' }
+    mailer_args        { {} }
+
+    trait :delivered do
+      status            { :delivered }
+      mailer_message_id { SecureRandom.hex(6) }
+      completed_at      { Time.current }
+    end
+
+    trait :expired do
+      status       { 'expired' }
+      completed_at { Time.current }
+    end
+
+    trait :failed do
+      status       { 'failed' }
+      completed_at { Time.current }
+    end
+  end
+end

data/lib/mail_delivery_task.rb

@@ -0,0 +1,12 @@
+require 'active_job'
+require 'active_record'
+require 'active_support'
+require 'active_support/core_ext'
+require 'enumerize'
+require 'with_advisory_lock'
+
+require 'mail_delivery_task/version'
+
+require 'mail_delivery_task/base_attempt'
+
+Dir["#{File.dirname(__FILE__)}/mail_delivery_task/jobs/**/*.rb"].each { |file| require file }

data/lib/mail_delivery_task/base_attempt.rb

@@ -0,0 +1,125 @@
+module MailDeliveryTask
+  class InvalidStateError < StandardError; end
+
+  module BaseAttempt
+    extend ActiveSupport::Concern
+
+    included do
+      extend Enumerize
+
+      self.table_name = 'mail_delivery_task_attempts'
+
+      validates :mailer_class_name, presence: true
+      validates :mailer_action_name, presence: true
+      validates :mailer_message_id, uniqueness: true, allow_nil: true
+
+      serialize :mailer_args, JSON
+
+      scope :persisted, -> { where.not(persistence_token: nil) }
+      scope :pending, -> { where(status: :pending) }
+      scope :delivered, -> { where(status: :delivered) }
+      scope :expired, -> { where(status: :expired) }
+      scope :failed, -> { where(status: :failed) }
+
+      enumerize :status,
+                in: [:pending, :delivered, :expired, :failed],
+                predicates: true
+
+      before_create do
+        self.status ||= 'pending'
+      end
+
+      # For backward compatibility
+      alias_method :handle_deliver_error, :handle_deliver_mail_error
+    end
+
+    def deliver!
+      return unless may_schedule?
+
+      begin
+        reload
+        raise MailDeliveryTask::InvalidStateError unless pending?
+        increment!(:num_attempts)
+      rescue ActiveRecord::StaleObjectError
+        retry
+      end
+
+      mailer_class = mailer_class_name.constantize
+
+      mail = if mailer_args.present?
+        mailer_class.send(mailer_action_name, **mailer_args.symbolize_keys)
+      else
+        mailer_class.send(mailer_action_name)
+      end
+
+      with_lock do
+        raise MailDeliveryTask::InvalidStateError unless pending?
+
+        begin
+          self.persistence_token = persist_mail(mail) if should_persist?
+        rescue StandardError => e
+          # If Trunk is down, simply catch the exception so that we won't retry
+          # and thus send the mail multiple times.
+          handle_persist_mail_error(e)
+        end
+
+        begin
+          # Perform the actual delivery through SMTP / Butter
+          deliver_mail(mail)
+
+          # Note that this fails silently.
+          self.mailer_message_id = mail.message_id
+          update_status!('delivered')
+        rescue StandardError => e
+          handle_deliver_error(e)
+        end
+      end
+    end
+
+    def expire!
+      with_lock do
+        raise MailDeliveryTask::InvalidStateError unless pending?
+        update_status!('expired')
+      end
+    end
+
+    def fail!
+      with_lock do
+        raise MailDeliveryTask::InvalidStateError unless pending?
+        update_status!('failed')
+      end
+    end
+
+    def may_schedule?
+      scheduled_at.blank? || scheduled_at < Time.current
+    end
+
+    private
+
+    def deliver_mail(mail)
+      mail.deliver
+    end
+
+    # Override this if needed.
+    def persist_mail(mail)
+      raise NotImplementedError
+    end
+
+    # Override this if needed.
+    def handle_deliver_mail_error(e)
+      raise(e)
+    end
+
+    # Override this if needed.
+    def handle_persist_mail_error(e)
+      raise(e)
+    end
+
+    def update_status!(status)
+      update!(
+        status: status,
+        completed_at: Time.current,
+      )
+    end
+  end
+end

data/lib/mail_delivery_task/jobs/base_delivery_batch_job.rb

@@ -0,0 +1,18 @@
+module MailDeliveryTask
+  module BaseDeliveryBatchJob
+    extend ActiveSupport::Concern
+
+    included do
+      include MailDeliveryTask::BaseJob
+      queue_as :default
+    end
+
+    def perform
+      unless_already_executing do
+        ::MailDeliveryTask::Attempt.pending.where('scheduled_at IS ? || scheduled_at < ?', nil, Time.current).find_each do |task|
+          ::MailDeliveryJob.perform_later(task)
+        end
+      end
+    end
+  end
+end

data/lib/mail_delivery_task/jobs/base_delivery_job.rb

@@ -0,0 +1,23 @@
+module MailDeliveryTask
+  module BaseDeliveryJob
+    extend ActiveSupport::Concern
+
+    included do
+      include MailDeliveryTask::BaseJob
+      queue_as :default
+
+      # @override
+      private def lock_key
+        [self.class.name, @task.id]
+      end
+    end
+
+    def perform(task)
+      @task = task
+
+      unless_already_executing do
+        @task.deliver! if @task.reload.pending?
+      end
+    end
+  end
+end

data/lib/mail_delivery_task/jobs/base_job.rb

@@ -0,0 +1,16 @@
+module MailDeliveryTask
+  module BaseJob
+    extend ActiveSupport::Concern
+
+    private
+
+    def lock_key
+      self.class.name
+    end
+
+    def unless_already_executing(&block)
+      result = ActiveRecord::Base.with_advisory_lock_result(lock_key, timeout_seconds: 0, &block)
+      warn("AdvisoryLock owned by other instance of job: #{lock_key}. Exiting.") unless result.lock_was_acquired?
+    end
+  end
+end

data/lib/mail_delivery_task/testing.rb

@@ -0,0 +1 @@
+Dir["#{File.dirname(__FILE__)}/testing/**/*.rb"].each { |file| require file }

data/lib/mail_delivery_task/testing/mailer_helper.rb

@@ -0,0 +1,114 @@
+module MailDeliveryTask
+  module Testing
+    module MailerHelper
+      extend RSpec::Matchers::DSL
+
+      # Tests that a provided mail object is deliverable.
+      #
+      # Usage:
+      #
+      #   expect(mail).to be_deliverable
+      #
+      matcher :be_deliverable do
+        match do |actual|
+          expect { actual.deliver_now }.to change { ActionMailer::Base.deliveries.count }.by(1)
+        end
+      end
+
+      # Tests that a provided mail object has the expected attributes.
+      #
+      # Usage:
+      #
+      #   expect(mail).to have_mailer_attributes(
+      #     from: 'from@.squareup.com',
+      #     reply_to: 'reply_to@.squareup.com',
+      #     to: ['person_1@squareup.com', 'person_2@squareup.com'],
+      #     bcc: 'bcc@squareup.com',
+      #     subject: 'My random subject',
+      #   )
+      #
+      matcher :have_mailer_attributes do |from:, reply_to: nil, to:, bcc: nil, subject:|
+        match(notify_expectation_failures: true) do |actual|
+          expect(actual).to have_attributes(
+            from: Array(from),
+            reply_to: Array(reply_to),
+            to: Array(to),
+            bcc: Array(bcc),
+            subject: subject,
+          )
+        end
+      end
+
+      # Tests that a string matches the content of a fixture file. Also provides
+      # convenience methods to be able to update the given fixture.
+      #
+      # Set `update_fixture` to true in order to automatically overwrite existing
+      # fixture files with latest expected text.  Note that tests will *always*
+      # fail as long as `update_fixture` is set to true.
+      #
+      # Usage:
+      #
+      #   expect('my_random_text').to match_fixture('spec/fixtures/dummy.html')
+      #   expect('my_random_text').to match_fixture('spec/fixtures/dummy.html', update_fixture: true)
+      #
+      matcher :match_fixture do |fixture_file, update_fixture: false|
+        match do |actual|
+          # Trim all trailing whitespace from the actual generated (to avoid
+          # codebase from having any trailing whitespace)
+          trimmed_actual = actual.gsub(/[ \t]+$/, '')
+
+          if update_fixture
+            # Update the fixture file with actual content
+            path = File.dirname(fixture_file)
+            FileUtils.mkdir_p(path)
+            FileUtils.touch(fixture_file)
+            File.open(fixture_file, 'w+') do |file|
+              file.write(trimmed_actual)
+            end
+
+            # Make sure the spec fails
+            false
+          else
+            begin
+              expect(trimmed_actual).to eq(File.read(fixture_file))
+            rescue
+              # Make sure the spec fails
+              false
+            end
+          end
+        end
+
+        failure_message do |actual|
+          if update_fixture
+            'Expected update_fixture to be false'
+          else
+            differ = RSpec::Support::Differ.new(
+              object_preparer: proc { |o| RSpec::Matchers::Composable.surface_descriptions_in(o) },
+              color: RSpec::Matchers.configuration.color?,
+            )
+            begin
+              expected = File.read(fixture_file)
+              <<~MESSAGE
+                expected: #{expected.inspect}
+                     got: #{actual.inspect}
+
+                Diff: #{differ.diff(actual, expected)}
+
+                To update existing fixtures, toggle the `update_fixture` option.
+
+                Example: match_fixture('spec/fixtures/dummy.html', update_fixture: true)
+              MESSAGE
+            rescue
+              <<~MESSAGE
+                Fixture file #{fixture_file} does not exist yet. Please
+                generate fixtures using the `update_fixture` option.
+
+                Example: match_fixture('spec/fixtures/dummy.html', update_fixture: true)
+              MESSAGE
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mail_delivery_task/version.rb

@@ -0,0 +1,3 @@
+module MailDeliveryTask
+  VERSION = '0.0.1'
+end

data/mail_delivery_task.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mail_delivery_task/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'mail_delivery_task'
+  spec.version       = MailDeliveryTask::VERSION
+  spec.authors       = ['James Chang']
+  spec.email         = ['jchang@squareup.com']
+
+  spec.summary       = 'Async email delivery'
+  spec.homepage      = 'https://github.com/square/mail_delivery_task'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.executables = spec.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.3'
+
+  spec.add_runtime_dependency 'activejob', '>= 4.2.0', '< 5.2'
+  spec.add_runtime_dependency 'activerecord', '>= 4.2.0', '< 5.2'
+  spec.add_runtime_dependency 'activesupport', '>= 4.2.0', '< 5.2'
+
+  spec.add_runtime_dependency 'enumerize'
+  spec.add_runtime_dependency 'with_advisory_lock'
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: mail_delivery_task
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- James Chang
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: enumerize
+  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'
+- !ruby/object:Gem::Dependency
+  name: with_advisory_lock
+  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: 
+email:
+- jchang@squareup.com
+executables:
+- console
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGES.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/generators/mail_delivery_task/install_generator.rb
+- lib/generators/mail_delivery_task/templates/create_mail_delivery_task_attempts.rb
+- lib/generators/mail_delivery_task/templates/mail_delivery_batch_job.rb.erb
+- lib/generators/mail_delivery_task/templates/mail_delivery_batch_job_spec.rb.erb
+- lib/generators/mail_delivery_task/templates/mail_delivery_job.rb.erb
+- lib/generators/mail_delivery_task/templates/mail_delivery_job_spec.rb.erb
+- lib/generators/mail_delivery_task/templates/mail_delivery_task_attempt.rb.erb
+- lib/generators/mail_delivery_task/templates/mail_delivery_task_attempt_spec.rb.erb
+- lib/generators/mail_delivery_task/templates/mail_delivery_task_attempts.rb.erb
+- lib/mail_delivery_task.rb
+- lib/mail_delivery_task/base_attempt.rb
+- lib/mail_delivery_task/jobs/base_delivery_batch_job.rb
+- lib/mail_delivery_task/jobs/base_delivery_job.rb
+- lib/mail_delivery_task/jobs/base_job.rb
+- lib/mail_delivery_task/testing.rb
+- lib/mail_delivery_task/testing/mailer_helper.rb
+- lib/mail_delivery_task/version.rb
+- mail_delivery_task.gemspec
+homepage: https://github.com/square/mail_delivery_task
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Async email delivery
+test_files: []