qu_mailer 0.1.0

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,74 @@
+PATH
+  remote: .
+  specs:
+    qu_mailer (0.1.0)
+      actionmailer (>= 3.0.0)
+      qu (>= 0.1.3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.1.1)
+      actionpack (= 3.1.1)
+      mail (~> 2.3.0)
+    actionpack (3.1.1)
+      activemodel (= 3.1.1)
+      activesupport (= 3.1.1)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      i18n (~> 0.6)
+      rack (~> 1.3.2)
+      rack-cache (~> 1.1)
+      rack-mount (~> 0.8.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.0.2)
+    activemodel (3.1.1)
+      activesupport (= 3.1.1)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activesupport (3.1.1)
+      multi_json (~> 1.0)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.0)
+    mail (2.3.0)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.17.2)
+    multi_json (1.0.3)
+    polyglot (0.3.3)
+    qu (0.1.3)
+      multi_json
+    rack (1.3.5)
+    rack-cache (1.1)
+      rack (>= 0.4)
+    rack-mount (0.8.3)
+      rack (>= 1.0.0)
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rspec (2.7.0)
+      rspec-core (~> 2.7.0)
+      rspec-expectations (~> 2.7.0)
+      rspec-mocks (~> 2.7.0)
+    rspec-core (2.7.1)
+    rspec-expectations (2.7.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.7.0)
+    sprockets (2.0.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  qu_mailer!
+  rspec (>= 2.6.0)

data/README.md

@@ -0,0 +1,82 @@
+# QuMailer
+
+QuMailer is a library for the asynchronous delivery of emails sent out by ActionMailer in Rails 3 applications. It is heavily inspired by ResqueMailer.
+
+Email jobs created by QuMailer are processed by [Qu](https://github.com/bkeepers/qu), a Ruby library for queuing and processing background jobs.
+
+## Installation
+
+It is assumed that you are using Qu. If you aren’t already using it, please visit the [Qu project page](https://github.com/bkeepers/qu) for details on getting set up.
+
+### Rails 3
+
+Add the QuMailer gem to your `Gemfile`.
+
+``` ruby
+gem 'qu_mailer'
+```
+
+## Usage
+
+Include QuMailer in your ActionMailer subclass(es):
+
+``` ruby
+class MyMailer < ActionMailer::Base
+  include Qu::Mailer
+end
+```
+
+Fire up Qu with a 'mailer' queue:
+
+``` sh
+$ bundle exec rake qu:work QUEUES=mailer,default
+```
+
+Now, when you send a `deliver` message to an action in `MyMailer`, it will be placed on Qu’s *mailer* queue, and a Qu worker will deliver it in due course. If you want to bybass Qu in a particular scenario and send the email synchronously, then use `deliver!`.
+
+It is recommended that instead of passing objects to your emails as parameters, record identifiers are used instead. Jobs are handled in a separate process.
+
+## Configuration
+
+### Queue Name
+
+QuMailer defaults to a queue called `mailer`. You can change the name of the queue using an initializer. 
+
+`config/initializers/qu_mailer.rb`:
+
+``` ruby
+  Qu::Mailer.default_queue_name = 'asynchronous_electronic_mailbox'
+```
+
+### Excluded Environments
+
+You may want to prevent QuMailer from sending out email in certain environments. By default QuMailer exludes the test environment. You may add additional excluded environments using an initializer.
+
+`config/initializers/qu_mailer.rb`:
+
+``` ruby
+  Qu::Mailer.excluded_environments << :cucumber
+```
+
+## License
+
+Copyright (c) 2011 Philip Poots
+
+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/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), "lib", "qu_mailer")

data/lib/qu_mailer.rb

@@ -0,0 +1,84 @@
+module Qu
+  module Mailer
+    class << self
+      attr_accessor :default_queue_target, :default_queue_name
+      attr_reader :excluded_environments
+
+      def excluded_environments=(envs)
+        @excluded_environments = [*envs].map(&:to_sym)
+      end
+
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    self.default_queue_target = ::Qu
+    self.default_queue_name = 'mailer'
+    self.excluded_environments = [:test]
+
+    module ClassMethods
+      def current_env
+        ::Rails.env
+      end
+
+      def method_missing(method_name, *args)
+        return super if environment_excluded?
+
+        if action_methods.include?(method_name.to_s)
+          MessageDecoy.new(self, method_name, *args)
+        else
+          super
+        end
+      end
+
+      def perform(action, *args)
+        self.send(:new, action, *args).message.deliver
+      end
+
+      def environment_excluded?
+        !ActionMailer::Base.perform_deliveries || excluded_environment?(current_env)
+      end
+
+      def excluded_environment?(name)
+        ::Qu::Mailer.excluded_environments && ::Qu::Mailer.excluded_environments.include?(name.to_sym)
+      end
+
+      def qu
+        ::Qu::Mailer.default_queue_target
+      end
+
+      def queue
+        ::Qu::Mailer.default_queue_name
+      end
+
+      class MessageDecoy
+        def initialize(mailer_class, method_name, *args)
+          @mailer_class = mailer_class
+          @method_name = method_name
+          *@args = *args
+        end
+
+        def qu
+          ::Qu::Mailer.default_queue_target
+        end
+
+        def actual_message
+          @actual_message ||= @mailer_class.send(:new, @method_name, *@args).message
+        end
+
+        def deliver
+          qu.enqueue(@mailer_class, @method_name, *@args)
+        end
+    
+        def deliver!
+          actual_message.deliver!
+        end
+
+        def method_missing(method_name, *args)
+          actual_message.send(method_name, *args)
+        end
+      end
+    end
+  end
+end

data/qu_mailer.gemspec

@@ -0,0 +1,34 @@
+Gem::Specification.new do |s|
+  s.name     = 'qu_mailer'
+  s.version  = '0.1.0'
+  s.platform = Gem::Platform::RUBY
+
+  s.summary     = 'Asynchronous email delivery for ActionMailer via Qu'
+  s.description = 'QuMailer is a Rails plugin for delivering email asynchronously from ActionMailer via the Qu queuing library.'
+
+  s.homepage = 'https://github.com/pootsbook/qu_mailer'
+  s.authors  = ['Philip Poots']
+  s.email    = ['philip.poots@gmail.com']
+
+  s.files         = [
+    'lib/qu_mailer.rb', 
+    'spec/qu_mailer_spec.rb', 
+    'spec/spec_helper.rb', 
+    'init.rb', 
+    'Gemfile', 
+    'Gemfile.lock', 
+    'README.md',
+    'qu_mailer.gemspec'
+  ]
+  s.test_files    = [
+    'spec/spec_helper.rb',
+    'spec/qu_mailer_spec.rb'
+  ] 
+  s.require_paths = ['lib']
+
+  s.required_ruby_version = ::Gem::Requirement.new('~> 1.9')
+
+  s.add_dependency 'qu', '>= 0.1.3'
+  s.add_dependency 'actionmailer', '>= 3.0.0'
+  s.add_development_dependency 'rspec', '>= 2.6.0'
+end

data/spec/qu_mailer_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+
+class FakeQu
+  def self.enqueue(*args); end
+end
+
+class Rails3Mailer < ActionMailer::Base
+  include Qu::Mailer
+  default :from => 'sender@example.org', :subject => 'Subject'
+  MAIL_PARAMS = { :to => 'recipient@example.org' }
+
+  def test_mail(*params)
+    Qu::Mailer.success!
+    mail(*params)
+  end
+end
+
+describe Qu::Mailer do
+  let(:qu) { FakeQu }
+  
+  before do
+    Qu::Mailer.default_queue_target = qu
+    Qu::Mailer.stub(:success!)
+    Rails3Mailer.stub(:current_env => :test)
+  end
+
+  describe "qu" do
+    it "allows overriding of the default queue target (for testing)" do
+      Qu::Mailer.default_queue_target = FakeQu
+      Rails3Mailer.qu.should == FakeQu
+    end
+  end
+
+  describe "queue" do
+    it "defaults to the 'mailer' queue" do
+      Rails3Mailer.queue.should == "mailer"
+    end
+
+    it "allows overriding of the default queue name" do
+      Qu::Mailer.default_queue_name = "postal"
+      Rails3Mailer.queue.should == "postal"
+    end
+
+    describe "#deliver" do
+      before(:all) do
+        @delivery = -> {
+          Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).deliver
+        }
+      end
+
+      it "delivers the email synchronously" do
+        -> { @delivery.call }.should_not change(ActionMailer::Base.deliveries, :size)
+      end
+
+      it "places the deliver action on the Qu 'mailer' queue" do
+        qu.should_receive(:enqueue).with(Rails3Mailer, :test_mail, Rails3Mailer::MAIL_PARAMS)
+        @delivery.call
+      end
+
+      it "does not invoke the method body more than once" do
+        Qu::Mailer.should_not_receive(:success!)
+        Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).deliver
+      end
+
+      context "when current environment is excluded" do
+        it "does not deliver through Qu for excluded environments" do
+          Qu::Mailer.stub(:excluded_environments => [:custom])
+          Rails3Mailer.should_receive(:current_env).and_return(:custom)
+          qu.should_not_receive(:enqueue)
+          @delivery.call
+        end
+      end
+    end
+  end
+
+  describe "#deliver!" do
+    it "delivers the email synchronously" do
+      -> { 
+        Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).deliver! 
+      }.should change(ActionMailer::Base.deliveries, :size).by(1)
+    end
+  end
+
+  describe "perform" do
+    it "performs a queued mailer job" do
+      -> { 
+        Rails3Mailer.perform(:test_mail, Rails3Mailer::MAIL_PARAMS)
+      }.should change(ActionMailer::Base.deliveries, :size).by(1)
+    end
+  end
+
+  describe "original mail methods" do
+    it "is preserved" do
+      Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).subject.should == 'Subject'
+      Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).from.should include('sender@example.org') 
+      Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).to.should include('recipient@example.org')
+    end
+
+    it "requires execution of the method body prior to queuing" do
+      Qu::Mailer.should_receive(:success!).once
+      Rails3Mailer.test_mail(Rails3Mailer::MAIL_PARAMS).subject
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'bundler/setup'
+
+require 'action_mailer'
+require 'qu_mailer'
+
+Qu::Mailer.excluded_environments = []
+ActionMailer::Base.delivery_method = :test

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: qu_mailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Philip Poots
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-13 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: qu
+  requirement: &70130676481580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: *70130676481580
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: &70130676480700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70130676480700
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70130676479720 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.6.0
+  type: :development
+  prerelease: false
+  version_requirements: *70130676479720
+description: QuMailer is a Rails plugin for delivering email asynchronously from ActionMailer
+  via the Qu queuing library.
+email:
+- philip.poots@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/qu_mailer.rb
+- spec/qu_mailer_spec.rb
+- spec/spec_helper.rb
+- init.rb
+- Gemfile
+- Gemfile.lock
+- README.md
+- qu_mailer.gemspec
+homepage: https://github.com/pootsbook/qu_mailer
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ~>
+    - !ruby/object:Gem::Version
+      version: '1.9'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Asynchronous email delivery for ActionMailer via Qu
+test_files:
+- spec/spec_helper.rb
+- spec/qu_mailer_spec.rb