action_mailer-enqueable 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in action_mailer-enqueable.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Eric Chapweske
+
+MIT License
+
+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,36 @@
+# ActionMailer::Enqueable
+
+Drop in support for using queues with existing delivery methods. Works with mailers that accept ActiveRecord, and simple JSON-compatible objects as arguments.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'action_mailer-enqueable'
+
+## Usage
+
+```ruby
+class EnqueableMailer < ActionMailer::Base
+  extend ActionMailer::Enqueable
+
+  self.delivery_method = :test
+  self.queue = MailRenderingJob
+
+  def welcome(user)
+    recipients   'You'
+    from         'Me'
+
+    body "Email: Hello, #{user}"
+  end
+
+end
+
+class MailRenderingJob
+
+  def self.enqueue(deferred)
+    Resque.enqueue(deferred.encoded)
+  end
+
+end
+````

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+#require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test

data/action_mailer-enqueable.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/action_mailer/enqueable/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Eric Chapweske"]
+  gem.email         = ["eac@zendesk.com"]
+  gem.description   = "Serialize and enqueue deliveries for existing mailers"
+  gem.summary       = %q{}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "action_mailer-enqueable"
+  gem.require_paths = ["lib"]
+  gem.version       = ActionMailer::Enqueable::VERSION
+
+  gem.add_development_dependency 'activesupport', '2.3.16'
+  gem.add_development_dependency 'actionmailer',  '2.3.16'
+end

data/lib/action_mailer/enqueable.rb

@@ -0,0 +1,27 @@
+require 'action_mailer/enqueable/version'
+require 'action_mailer/enqueable/deferred'
+require 'active_support/core_ext/class/attribute'
+
+module ActionMailer::Enqueable
+
+  def self.extended(base)
+    base.class_attribute :queue
+  end
+
+  def method_missing(method_symbol, *parameters) #:nodoc:
+    if match = matches_dynamic_method?(method_symbol)
+      if queue && match[1] == 'deliver'
+        enqueue(match[2], parameters)
+      else
+        super
+      end
+    end
+  end
+
+  def enqueue(method_id, arguments)
+    deferred = Deferred.new(:mailer_name => name, :method_id => method_id, :arguments => arguments)
+    queue.enqueue(deferred)
+    deferred
+  end
+
+end

data/lib/action_mailer/enqueable/deferred.rb

@@ -0,0 +1,86 @@
+require 'action_mailer/enqueable/record_encoder'
+require 'active_support/core_ext/hash'
+
+module ActionMailer::Enqueable
+  class Deferred
+    class Invalid < ArgumentError
+    end
+
+    def self.from_json(params)
+      from_hash(ActiveSupport::JSON.decode(params))
+    end
+
+    def self.from_hash(params)
+      decoded = encoder.decode(params)
+
+      new(decoded)
+    end
+
+    def self.encoder
+      RecordEncoder
+    end
+
+    attr_reader :errors, :params
+
+    def initialize(params)
+      @params = params
+      @params.symbolize_keys!
+    end
+
+    # ActionMailer does some bizzare stuff with #new.
+    def mailer
+      @mailer ||= begin
+                    mailer = mailer_class.allocate
+                    mailer.send(:initialize, method_id, *arguments)
+                    mailer
+                  end
+    end
+
+    def mailer_class
+      mailer_name.constantize
+    end
+
+    def mailer_name
+      params[:mailer_name]
+    end
+
+    def method_id
+      params[:method_id]
+    end
+
+    def arguments
+      params[:arguments]
+    end
+
+    def attributes
+      { :mailer_name => mailer_name, :method_id => method_id, :arguments => arguments }
+    end
+
+    def validate!
+      valid? || raise(Invalid.new("Deferred mailer is invalid: #{errors.inspect}"))
+    end
+
+    def valid?
+      @errors = attributes.map do |name, value|
+        "#{name} can't be nil" if value.nil?
+      end
+      @errors.compact!
+
+      @errors.empty?
+    end
+
+    def to_json(options = {})
+      ActiveSupport::JSON.encode(encoded)
+    end
+
+    def encoded
+      self.class.encoder.encode(params)
+    end
+
+    def ==(other)
+      other.respond_to?(:params) &&
+        other.params == params
+    end
+
+  end
+end

data/lib/action_mailer/enqueable/record_encoder.rb

@@ -0,0 +1,76 @@
+require 'active_support'
+
+# Prepare ActiveRecord objects for safe serialization.
+#
+# user = User.first
+# => #<User id: 1, account_id: 1, name: 'Buddhy'>
+# RecordEncoder.encode(user)
+# => { :class => 'User', :id => 1 }
+# RecordEncoder.decode(user)
+# => #<User id: 1, account_id: 1, name: 'Buddhy'>
+#
+module ActionMailer::Enqueable::RecordEncoder
+  class RecordIdMissingError < ArgumentError
+    def initialize(record)
+      @record = record
+    end
+
+    def message
+      "ActiveRecords must have an id to be serialized: (#{@record.inspect})"
+    end
+  end
+  CLASS = 'class'.freeze
+  ID    = 'id'.freeze
+
+  extend self
+
+  def encode(params)
+    encoded = params.map do |argument|
+      case argument
+      when ActiveRecord::Base
+        encode_active_record(argument)
+      when Array, Hash
+        encode(argument)
+      when NilClass, TrueClass, FalseClass, Numeric, String, Symbol
+        argument
+      else
+        raise ArgumentError.new("Cannot encode #{argument} (#{argument.class})")
+      end
+    end
+
+    params.is_a?(Hash) ? Hash[encoded] : encoded
+  end
+
+  def decode(params)
+    decoded = params.map do |argument|
+      case argument
+      when Hash
+        active_record?(argument) ? decode_active_record(argument) : decode(argument)
+      when Array
+        decode(argument)
+      else
+        argument
+      end
+    end
+
+    params.is_a?(Hash) ? Hash[decoded] : decoded
+  end
+
+  protected
+
+  def decode_active_record(params)
+    params[CLASS].constantize.find(params[ID])
+  end
+
+  def active_record?(params)
+    params[CLASS] && params[ID]
+  end
+
+  def encode_active_record(record)
+    raise RecordIdMissingError.new(record) if record.id.to_s.empty?
+
+    { CLASS => record.class.name, ID => record.id }
+  end
+
+end
+

data/lib/action_mailer/enqueable/version.rb

@@ -0,0 +1,5 @@
+module ActionMailer
+  module Enqueable
+    VERSION = "1.0.0"
+  end
+end

data/test/deferred_test.rb

@@ -0,0 +1,130 @@
+require_relative 'helper'
+require 'action_mailer/enqueable/deferred'
+
+module ActiveRecord
+  class ActiveRecord::Base
+  end
+end
+
+class DeferredTest < MiniTest::Unit::TestCase
+
+  class User < ActiveRecord::Base
+
+    def self.find(id)
+      all.detect { |record| record.id == id }
+    end
+
+    def self.all
+      @all ||= [ User.new(:id => 1, :name => 'Squirrel'),
+        User.new(:id => 2, :name => 'Raccoon'),
+        User.new(:id => 3, :name => 'Bear') ]
+    end
+
+    attr_accessor :id, :name
+
+    def initialize(attributes)
+      self.id   = attributes[:id]
+      self.name = attributes[:name]
+    end
+
+  end
+
+  class DeferredMailer
+
+    def delivery_welcome(message, attributes)
+      "#{message} #{attributes['user'].join(',')}"
+    end
+
+  end
+
+  describe 'Deferred' do
+    before do
+      @deferred = ActionMailer::Enqueable::Deferred.new(
+        'mailer_name'  => 'DeferredMailer',
+        'method_id'    => 'welcome',
+        'arguments'    => [ 'Hello!', { 'users' => User.all } ])
+    end
+
+    it 'is equal to another deferred object when all params are equal' do
+      other = ActionMailer::Enqueable::Deferred.new(
+        'mailer_name'  => 'DeferredMailer',
+        'method_id'    => 'welcome',
+        'arguments'    => [ 'Hello!', { 'users' => User.all } ])
+
+      assert_equal @deferred, other
+    end
+
+    describe 'valid?' do
+
+      it 'is false when :mailer_name, :method_id or :arguments are missing' do
+        @deferred.params.delete(:mailer_name)
+        assert_equal false, @deferred.valid?
+      end
+
+      it 'is true when :mailer_name, :method_id, and :arguments are all present' do
+        assert_equal true, @deferred.valid?
+      end
+
+      it 'populates errors' do
+        assert_equal nil, @deferred.errors
+        @deferred.valid?
+        assert_equal [], @deferred.errors
+
+        @deferred.params.delete(:mailer_name)
+        @deferred.valid?
+        assert_equal [ "mailer_name can't be nil" ], @deferred.errors
+      end
+
+    end
+
+    describe 'validate!' do
+
+      it 'raises an error when invalid' do
+        @deferred.params.delete(:mailer_name)
+        assert_equal false, @deferred.valid?
+        assert_raises(ActionMailer::Enqueable::Deferred::Invalid) { @deferred.validate! }
+      end
+
+      it 'does not raise an error when valid' do
+        assert_equal true, @deferred.valid?
+        assert @deferred.validate!
+      end
+    end
+
+    describe 'to_json' do
+
+      it 'converts ActiveRecord objects into an easily deserializable form' do
+        encoded = '{"mailer_name":"DeferredMailer","method_id":"welcome","arguments":["Hello!",{"users":[{"class":"DeferredTest::User","id":1},{"class":"DeferredTest::User","id":2},{"class":"DeferredTest::User","id":3}]}]}'
+        assert_equal encoded, @deferred.to_json
+      end
+
+    end
+
+    describe 'from_json' do
+
+      it 'deserializes correctly' do
+        decoded = ActionMailer::Enqueable::Deferred.from_json(@deferred.to_json)
+        assert_equal 'DeferredMailer', decoded.mailer_name
+        assert_equal 'welcome',     decoded.method_id
+        assert_equal  [ 'Hello!', { 'users' => User.all } ], decoded.arguments
+      end
+
+    end
+
+    describe 'RecordEncoder' do
+
+      it "throws an exception when encoding records that can't be decoded" do
+        record = User.new(:id => nil)
+        exception = ActionMailer::Enqueable::RecordEncoder::RecordIdMissingError
+        encoder   = ActionMailer::Enqueable::RecordEncoder
+
+        assert_raises(exception) { encoder.encode({ :record => record }) }
+      end
+
+    end
+
+  end
+
+end
+
+

data/test/enqueable_test.rb

@@ -0,0 +1,55 @@
+require_relative 'helper'
+require 'action_mailer'
+require 'action_mailer/enqueable'
+
+class EnqueableTest < MiniTest::Unit::TestCase
+
+  class EnqueableMailer < ActionMailer::Base
+    extend ActionMailer::Enqueable
+
+    self.delivery_method = :test
+
+    def welcome(user)
+      recipients   'You'
+      from         'Me'
+
+      body "Email: Hello, #{user}"
+    end
+
+  end
+
+  class Queue < Array
+    alias enqueue push
+  end
+
+  describe 'Mailer with a queue' do
+    before do
+      @queue = Queue.new
+      EnqueableMailer.queue = @queue
+    end
+
+    it 'enqueues messages instead of deliverying them' do
+      deferred = EnqueableMailer.deliver_welcome('Buddhy')
+      assert_equal EnqueableMailer, deferred.mailer_class
+      assert_equal 'welcome',       deferred.method_id
+      assert_equal [ 'Buddhy' ],    deferred.arguments
+
+      deferred = ActionMailer::Enqueable::Deferred.new(:mailer_name => 'EnqueableTest::EnqueableMailer', :method_id => 'welcome', :arguments => [ 'Buddhy' ] )
+      assert_equal [ deferred ], @queue
+    end
+
+  end
+
+  describe 'Mailer without a queue' do
+    before do
+      EnqueableMailer.queue = nil
+    end
+
+    it 'delivers messages without attempting to enqueue' do
+      mail = EnqueableMailer.deliver_welcome('Buddhy')
+      assert_equal 'Email: Hello, Buddhy', mail.body
+    end
+
+  end
+
+end

data/test/helper.rb

@@ -0,0 +1,3 @@
+require 'bundler/setup'
+$LOAD_PATH.unshift(File.expand_path(File.join(File.dirname(__FILE__), '../lib'))) # lib
+require 'minitest/autorun'

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: action_mailer-enqueable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Eric Chapweske
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.16
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.16
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.16
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.16
+description: Serialize and enqueue deliveries for existing mailers
+email:
+- eac@zendesk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- action_mailer-enqueable.gemspec
+- lib/action_mailer/enqueable.rb
+- lib/action_mailer/enqueable/deferred.rb
+- lib/action_mailer/enqueable/record_encoder.rb
+- lib/action_mailer/enqueable/version.rb
+- test/deferred_test.rb
+- test/enqueable_test.rb
+- test/helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: ''
+test_files:
+- test/deferred_test.rb
+- test/enqueable_test.rb
+- test/helper.rb