ar_mailer_revised 0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57ad9dcf569b1f53fcc93b4b7100e67ea077c08f
-  data.tar.gz: bbf2faed6943104ab53f078fbd4ce1c64586de6a
+  metadata.gz: 0aef767abd393af9428a1bbea305cd024d6cf994
+  data.tar.gz: 4011b3fa47058260ebdeb930c6c2c49ba9396539
 SHA512:
-  metadata.gz: 8768cb5e338630a98e615513234066f37bb269deba0b73bc0b2ee5053257e82721e4884c7c856759cb3378f9c4e769b0bff763cb78009d4be327bd925bb10291
-  data.tar.gz: ca22e7b7f016f3d5b50f9430a2762c10d71be0580fa54e83089baf3f41bcc7990b90aa9f66104e7e098a8d7bd4ec5a7b56c62c89f0ccc668f78b1a0da55ef5ae
+  metadata.gz: f7f9318aa6523598867b1d62c968d8d3fdc49ecd3842a0922c5525b7a0a87539f2a5c85c95a5048bd4858f8ed8d0687c3eb3a22aadfb58e66f863ce406d5548f
+  data.tar.gz: 3b51d939495ce060b28aae0fac4df7df49eeec32374d881ce67533badc69d41b6edee65260062f526cd2db53e70b35e0f34d1bb730d4308ab9c285824ad05def

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+cache: bundler
+
+rvm:
+  - 2.0.0
+  - 2.1
+
+script: 'bundle exec rake'
+
+notifications:
+  email:
+    recipients:
+      - stex@sterex.de
+    on_failure: change
+    on_success: never
+

data/README.md

@@ -1,6 +1,9 @@
 # ArMailerRevised
 
-[ArMailer](https://github.com/seattlerb/ar_mailer) is a great gem which allows you to store emails in your application's database and batch deliver
+[![Code Climate](https://codeclimate.com/github/Stex/ar_mailer_revised.png)](https://codeclimate.com/github/Stex/ar_mailer_revised)
+![Travis CI](https://travis-ci.org/Stex/ar_mailer_revised.svg?branch=rails_4)
+
+[ArMailer](https://github.com/seattlerb/ar_mailer) was a great gem which allows you to store emails in your application's database and batch deliver
 them later using a background task.
 
 However, it was not compatible with newer versions of Rails and also lacking some of the functionality I needed in my applications.
@@ -11,11 +14,9 @@ Especially, I wanted to use
 * custom SMTP settings per email
 * custom attributes directly in the email record to keep track of them
 
-**Note:** This is the Rails 2.3 version of ARMailer Revised.
-It does (and always will) **only support generating emails, not actually sending them**.
+ArMailerRevised contains this functionality, currently only for Rails >= 4.
 
-To actually send them, a Rails 4 application will be needed, this version was only made
-to let older existing applications use the email queue.
+**Important**: ArMailerRevised does only deliver emails using SMTP, not a sendmail executable.
 
 ## Installation
 
@@ -41,11 +42,13 @@ ArMailerRevised needs a few things to work correctly:
 
 All of them can be created using a generator:
 
-    $ ruby script/generate ar_mailer_revised MODEL_NAME
+    $ rails g ar_mailer_revised:install MODEL_NAME
 
-If you just want to add an old application to an existing Rails 4 email queue,
-simply delete the migration as you won't need it.
-Otherwise, migrate your application before continuing.
+If you don't specify a model name, the default name `Email` is used.
+ 
+Please migrate your database after the migration was created.
+If you need custom attributes (see below) in your email table, please 
+add them to the migration before migrating.
 
     $ rake db:migrate
 
@@ -54,19 +57,15 @@ Otherwise, migrate your application before continuing.
 First of all, you have to set ActionMailer to use the gem's delivery method.
 This can be done per environment or globally for the application using either
 
-```ruby
-config.action_mailer.delivery_method = :activerecord
-```
+    config.action_mailer.delivery_method = :activerecord
 
 or - not inside a configuration file
 
-```ruby
-ActionMailer::Base.delivery_method = :activerecord
-```
+    ActionMailer::Base.delivery_method = :activerecord
     
 ### SMTP-Settings
 
-ArMailerRevised accepts SMTP settings in the form ActionMailer::Base (v4) does.
+ArMailerRevised accepts SMTP settings in the form ActionMailer::Base does.
 Application wide settings have to be stored in ActionMailer::Base.smtp_settings.
 Please have a look at [ActionMailer::Base](http://api.rubyonrails.org/classes/ActionMailer/Base.html)
 
@@ -86,19 +85,16 @@ Below will be a growing list of demo SMTP settings for popular providers.
 ## Creating Emails
 
 ArMailerRevised uses the normal ActionMailer::Base templates, so you can write
-delivery-methods like you would for direct email sending.
-On delivering, the email will be stored in the database and not being sent directly.
-
-```ruby
-class TestMailer < ActionMailer::Base
-  def basic_email(recipients)
-     from    'test@example.com'
-     to      recipients
-     subject 'Hello, World'
-     body    'How are you?'
-  end
-end
-```
+deliver-methods like you would for direct email sending.
+On delivering, the email will be stored in the database and not being sent diretly.
+
+    class TestMailer < ActionMailer::Base
+      default from: 'from@example.com'
+    
+      def basic_email
+        mail(to: 'basic_email@example.com', subject: 'Basic Email Subject', body: 'Basic Email Body')
+      end
+    end
     
 ### Setting a custom delivery time
 
@@ -107,16 +103,10 @@ the resulting email record. One of them is +ar_mailer_delivery_time+.
 This method sets a time which determines the earliest sending time for this email, 
 in other words: If you set this time, the email won't be sent prior to it.
 
-```ruby
-def delayed_email
-  ar_mailer_delivery_time Time.now + 2.hours
-
-  from    'test@example.com'
-  to      recipients
-  subject 'Delayed Email'
-  body    'Yes, I am indeed delayed.'
-end
-```
+    def delayed_email
+      ar_mailer_delivery_time Time.now + 2.hours
+      mail(to: 'delayed_email@example.com', subject: 'Delayed Email Subject', :body => 'Delayed Email Body')
+    end
     
 **Important**: It may happen that the Rails logging output of the generated mail may still contain
 custom attributes (like the delivery time) in its header. This happens because ActionMailer will
@@ -127,24 +117,19 @@ log the email before actually delivering it. The generated email will **not** co
 It is possible to set own SMTP settings for each email in the system which will then be used for delivery.
 These settings may contain everything the global settings do (see above).
 
-```ruby
-def custom_smtp_email
-  ar_mailer_smtp_settings({
-    :address   => 'localhost',
-    :port      => 25,
-    :domain    => 'localhost.localdomain',
-    :user_name => 'some.user',
-    :password  => 'some.password',
-    :authentication => :plain,
-    :enable_starttls_auto => true
-  })
-    
-  from    'test@example.com'
-  to      recipients
-  subject 'Custom Settings Email'
-  body    'I use custom settings (but will go back to the default ones if these are incorrect)'
-end
-```
+    def custom_smtp_email
+      ar_mailer_smtp_settings({
+        :address   => 'localhost',
+        :port      => 25,
+        :domain    => 'localhost.localdomain',
+        :user_name => 'some.user',
+        :password  => 'some.password',
+        :authentication => :plain,
+        :enable_starttls_auto => true
+      })
+        
+      mail(to: 'custom_smtp_email@example.com', subject: 'Custom SMTP Email Subject', :body => 'Custom SMTP Email Body')
+    end
 
 **Important**: As the mailer has to use the password to connect to the SMTP server, it is stored in the database in plain text!
 If this means a security issue to you, please use only the global settings which are loaded from the environment and not stored in the database.
@@ -160,23 +145,22 @@ You can add custom attributes to the email table simply by altering the generate
     
 In the email delivering method, these attributes may then be filled with the actual data using the `ar_mailer_attribute` helper method:
 
-```ruby
-def custom_attribute_email
-  ar_mailer_attribute :a_number, 42
-
-  from    'test@example.com'
-  to      recipients
-  subject 'Custom Attribute Email'
-  body    'I have a custom attribute.'
-end
-```
+    def custom_attribute_email
+      ar_mailer_attribute :a_number, 42
+      mail(to: 'custom_attribute_email@example.com', subject: 'Custom Attribute Email Subject', :body => 'Custom Attribute Email Body')
+    end
     
 ### Sending Emails
 
-As mentioned above, this version of ARMailer Revised does not allow sending emails.
+ArMailerRevised comes with an executable called `ar_sendmail` which can
+be accessed from the application's root directory.
+
+It accepts the argument `-h` (or `--help`), showing all available options.
+If you call it without options, it will run a single batch sending in the foreground and exist afterwards.
 
-Please use the Rails 4 version instead, e.g. with an own little application
-which uses the same database and only provides the email sending functionality.
+There will be daemon functionality in the future (mostly to avoid loading the application envirionment
+every single time emails are being sent), for now I suggest using a gem like [whenever](https://github.com/javan/whenever)
+to run the executable every X minutes.
     
 ### SMTP settings for common providers (to be extended)
 

data/ar_mailer_revised.gemspec

@@ -23,8 +23,13 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.3'
   spec.add_development_dependency 'yard', '~> 0.8'
   spec.add_development_dependency 'redcarpet', '~> 2.3'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'shoulda'
 
-  spec.add_dependency 'rails', '~> 2.3'
+  spec.add_dependency 'rails', '~> 4'
+  spec.add_dependency 'log4r'
+  spec.add_dependency 'hirb'
 
-  spec.required_ruby_version = '>= 1.8.7'
+  spec.required_ruby_version = '~> 2'
 end

data/bin/ar_sendmail

@@ -1,10 +1,5 @@
 #!/usr/bin/env ruby
 
-puts <<-EOS
-
-ar_sendmail is currently only available in the rails 4 version of ar_mailer_revised.
-The rails 2 version was only created to support email creation on older systems
-while still keeping the mail queue on a more up-to-date one.
-
-EOS
+require 'ar_mailer_revised/mailman'
+ArMailerRevised::Mailman.run
 

data/lib/action_mailer/ar_mailer.rb

@@ -2,6 +2,7 @@
 # Adds sending email through an ActiveRecord table as a delivery method for
 # ActionMailer.
 #
+
 class ActionMailer::Base
   #
   # Sets a custom email class attribute. It can be used
@@ -44,31 +45,57 @@ class ActionMailer::Base
   # Sets or simply returns an ar_mailer_setting
   #
   def ar_mailer_setting(key, value = nil)
-    @ar_mailer_settings ||= {}
+    if headers[:ar_mailer_settings]
+      settings = YAML.load(headers[:ar_mailer_settings]).stringify_keys
+    else
+      settings = {}
+    end
 
     if value
-      @ar_mailer_settings[key.to_s] = value
+      settings[key.to_s] = value
+      headers[:ar_mailer_settings] = YAML.dump(settings)
     else
-      @ar_mailer_settings[key.to_s]
+      settings[key.to_s]
     end
   end
 
-  #
-  # Custom ActionMailer delivery method.
-  # It does not actually send the email, but will create a record
-  # in the database instead to be sent later by the ar_sendmail executable.
-  #
-  def perform_delivery_activerecord(mail)
-    email_options = {}
-    email_options[:delivery_time] = ar_mailer_setting(:delivery_time)
-    email_options[:smtp_settings] = ar_mailer_setting(:smtp_settings)
-    email_options[:mail]          = mail.encoded
-    email_options[:from]          = (mail['return-path'] && mail['return-path'].spec) || mail.from.first
+end
+
+#
+# This class contains the actual sending functionality
+#
+module ActionMailer
+  class DeliveryMethodActiveRecord
+    #
+    # The delivery method seems to be called with a settings hash from the mail gem.
+    #
+    def initialize(settings)
+      @settings = settings
+    end
 
-    email_options.reverse_merge!(ar_mailer_setting(:custom_attributes) || {})
+    #
+    # Actually creates the email record in the database
+    #
+    def deliver!(mail)
+      if mail['ar_mailer_settings']
+        ar_settings = YAML.load(mail['ar_mailer_settings'].value).stringify_keys
+        mail['ar_mailer_settings'] = nil
+      else
+        ar_settings = {}
+      end
 
-    mail.destinations.each do |destination|
-      ArMailerRevised.email_class.create!(email_options.merge({:to => destination}))
+      email_options = {}
+      email_options[:delivery_time] = ar_settings.delete('delivery_time')
+      email_options[:smtp_settings] = ar_settings.delete('smtp_settings')
+      email_options[:mail]          = mail.encoded
+      email_options[:from]          = (mail['return-path'] && mail['return-path'].spec) || mail.from.first
+      email_options.reverse_merge!(ar_settings['custom_attributes'] || {})
+
+      mail.destinations.each do |destination|
+        ArMailerRevised.email_class.create!(email_options.merge({:to => destination}))
+      end
     end
   end
-end
+end
+
+

data/lib/ar_mailer_revised.rb

@@ -3,6 +3,8 @@ require 'action_mailer/ar_mailer'
 require 'ar_mailer_revised/email_scaffold'
 
 #Register the new delivery method
+ActionMailer::Base.add_delivery_method :activerecord, ActionMailer::DeliveryMethodActiveRecord
+
 module ArMailerRevised
   def self.configuration(&proc)
     @@config ||= OpenStruct.new({
@@ -29,7 +31,6 @@ module ArMailerRevised
   #   The email class' name
   #
   def self.email_class_name
-    self.configuration.email_class.classify
+    @@config.email_class.classify
   end
-
 end

data/lib/ar_mailer_revised/email_scaffold.rb

@@ -1,17 +1,30 @@
 #
 # Helper methods for the chosen email class
 #
+
 module ArMailerRevised
   module EmailScaffold
 
-    def self.included(base)
-      base.serialize :smtp_settings
+    extend ActiveSupport::Concern
+
+    included do
+      serialize :smtp_settings
 
       #Only emails which are to be sent immediately
-      base.named_scope :without_delayed, lambda { {:conditions => {:delivery_time => nil} }}
+      scope :without_delayed, lambda { where(:delivery_time => nil) }
+
+      #All emails which are ready to be sent.
+      #They are automatically sorted so that emails which already had a send attempt
+      #will be last in the queue as they might fail again.
+      scope :ready_to_deliver, lambda { where('delivery_time IS NULL OR delivery_time <= ?', Time.now).order('last_send_attempt ASC') }
 
       #All emails which are to be sent in the future
-      base.named_scope :delayed, lambda { {:conditions => ['delivery_time > ?', Time.now]}}
+      scope :delayed, lambda { where('delivery_time > ?', Time.now) }
+
+      #Applies a +limit+ to the finder if batch_size is set
+      scope :with_batch_size, lambda { |batch_size|
+        batch_size ? {:limit => batch_size} : {}
+      }
     end
 
     #
@@ -21,12 +34,5 @@ module ArMailerRevised
     def previously_attempted?
       last_send_attempt > 0
     end
-
-    #
-    # @return [Boolean] +true+ if this email is to be sent in the future
-    #
-    def delayed?
-      !!(delivery_time && delivery_time > Time.now)
-    end
   end
 end

data/lib/ar_mailer_revised/helpers/command_line.rb

@@ -0,0 +1,198 @@
+require 'hirb'
+require 'optparse'
+
+module ArMailerRevised
+  module Helpers
+    module CommandLine
+
+      class RailsEnvironmentFailed < StandardError;
+      end
+
+      def self.included(base)
+        base.class_eval do
+          base.send :extend, ClassMethods
+        end
+      end
+
+      module ClassMethods
+
+        ##
+        # Processes +args+ and runs as appropriate
+
+        def run(args = ARGV)
+          options = process_args(args)
+
+          if options[:display_queue]
+            display_mail_queue(options[:display_queue])
+            exit
+          end
+
+          new(options).run
+
+        rescue SystemExit
+          raise
+        rescue SignalException
+          exit
+        rescue Exception => e
+          $stderr.puts "Unhandled exception #{e.message}(#{e.class}):"
+          $stderr.puts "\t#{e.backtrace.join "\n\t"}"
+          exit -2
+        end
+
+        ##
+        # Prints a list of unsent emails and the last delivery attempt, if any.
+        # Only emails which are ready to deliver are displayed
+        #
+        def display_mail_queue(what)
+          emails = case what
+                     when 'all' then
+                       puts 'Showing all emails in the system'
+                       ArMailerRevised.email_class.all
+                     when 'deliverable' then
+                       puts 'Showing emails ready to deliver'
+                       ArMailerRevised.email_class.ready_to_deliver
+                     when 'delayed' then
+                       puts 'Showing delayed emails'
+                       ArMailerRevised.email_class.delayed
+                     else
+                       []
+                   end
+        puts 'Mail queue is empty' and return if emails.empty?
+        puts Hirb::Helpers::AutoTable.render emails, :fields => [:from, :to, :delivery_time, :last_send_attempt, :updated_at]
+      end
+
+      def process_args(args)
+        name = File.basename $0
+
+        options             = {}
+        options[:chdir]     = '.'
+        options[:max_age]   = 86400 * 7
+        options[:rails_env] = ENV['RAILS_ENV']
+        options[:log_level] = 'info'
+        options[:verbose]   = false
+
+        opts = OptionParser.new do |opts|
+          opts.banner = "Usage: #{name} [options]"
+          opts.separator ''
+
+          opts.separator "#{name} scans the email table for new messages and sends them to the"
+          opts.separator "website's configured SMTP host."
+          opts.separator ''
+          opts.separator "#{name} must be run from a Rails application's root."
+
+          opts.separator ''
+          opts.separator 'Sendmail options:'
+
+          opts.on("-b", "--batch-size BATCH_SIZE",
+                  "Maximum number of emails to send per delay",
+                  "Default: Deliver all available emails", Integer) do |batch_size|
+            options[:batch_size] = batch_size
+          end
+
+          opts.on("--max-age MAX_AGE",
+                  "Maxmimum age for an email. After this",
+                  "it will be removed from the queue.",
+                  "Set to 0 to disable queue cleanup.",
+                  "Default: #{options[:max_age]} seconds", Integer) do |max_age|
+            options[:max_age] = max_age
+          end
+
+          opts.on('--mailq [all|deliverable|delayed]',
+                  'Display a list of emails waiting to be sent',
+                  'Default: all') do |mailq|
+            options[:display_queue] = mailq || 'all'
+          end
+
+          opts.separator ''
+          opts.separator 'Generic Options:'
+
+          opts.on('-l', '--log-file PATH',
+                  'Custom log file location at PATH. May also be "stdout" or "stderr" for console output',
+                  'Default: log/environment.log') do |path|
+            dir = File.dirname(path)
+            usage opts, "#{dir} is not an existing directory" unless File.exists?(dir) && File.directory?(dir)
+            usage opts, "#{path} is a directory" if File.directory?(path)
+            options[:log_file] = path
+          end
+
+          opts.on('--log-level LEVEL',
+                  "Set the mailer's log LEVEL",
+                  "Default: #{options[:log_level]}") do |level|
+            usage opts, "Invalid log-level: #{level}" unless %w[debug info warn error fatal].include?(level.to_s.downcase)
+            options[:log_level] = level
+          end
+
+          opts.on("-c", "--chdir PATH",
+                  "Use PATH for the application path",
+                  "Default: #{options[:chdir]}") do |path|
+            usage opts, "#{path} is not a directory" unless File.directory? path
+            usage opts, "#{path} is not readable" unless File.readable? path
+            options[:chdir] = path
+          end
+
+          opts.on("-e", "--environment RAILS_ENV",
+                  "Set the RAILS_ENV constant",
+                  "Default: #{options[:rails_env]}") do |env|
+            options[:rails_env] = env
+          end
+
+          opts.on("-v", "--[no-]verbose",
+                  "Be verbose",
+                  "Default: #{options[:verbose]}") do |verbose|
+            options[:verbose] = verbose
+          end
+
+          opts.on("-h", "--help",
+                  "You're looking at it") do
+            usage opts
+          end
+
+          opts.on("--version", "Version of ARMailer") do
+            usage "ar_mailer_revised #{VERSION}"
+          end
+
+          opts.separator ''
+        end
+
+        opts.parse! args
+
+        ENV['RAILS_ENV'] = options[:rails_env]
+
+        begin
+          load_rails_environment(options[:chdir])
+        rescue RailsEnvironmentFailed
+          usage opts, <<-EOF
+#{name} must be run from a Rails application's root to deliver email.
+#{Dir.pwd} does not appear to be a Rails application root.
+          EOF
+        end
+
+        options
+      end
+
+      #
+      # Loads the complete rails environment
+      #
+      def load_rails_environment(base_path)
+        Dir.chdir(base_path) do
+          require File.join(base_path, 'config/environment')
+          require 'action_mailer/ar_mailer'
+        end
+      rescue LoadError => e
+        puts e
+        raise RailsEnvironmentFailed
+      end
+
+      def usage(opts, message = nil)
+        if message then
+          $stderr.puts message
+          $stderr.puts
+        end
+
+        $stderr.puts opts
+        exit 1
+      end
+    end
+  end
+end
+end