ar_mailer_revised 0.1 → 1.0.0

data/lib/ar_mailer_revised/helpers/general.rb

@@ -0,0 +1,81 @@
+#
+# This module contains helper functionality for the Mailman class
+# that handles the actual email sending as a batch process.
+#
+# @author Stefan Exner <stex@sterex.de>
+#
+
+require 'log4r'
+
+module ArMailerRevised
+  module Helpers
+    module General
+      #
+      # Generates a logger object using Log4r
+      # The output file is determined by +#log_file+
+      #
+      # If the custom log file path is set to +stdout+ or +stderr+,
+      # these are used instead of a log file.
+      #
+      # @return [Log4r::Logger] the file output logger
+      #
+      def logger
+        unless @logger
+          @logger            = Log4r::Logger.new 'ar_mailer'
+
+          if %w[stdout stderr].include?(@options[:log_file])
+            outputter = Log4r::Outputter.send(@options[:log_file])
+          else
+            outputter = Log4r::FileOutputter.new('ar_mailer_log', :filename => log_file)
+          end
+
+          outputter.formatter = Log4r::PatternFormatter.new(:pattern => '[%5l - %c] %d :: %m')
+          @logger.outputters = outputter
+
+          @logger.level      = log_level
+        end
+        @logger
+      end
+
+      #
+      # Determines the correct log file location
+      # It defaults to the current environment's log file
+      # @todo Check if that interferes with Rails' logging process
+      #
+      # @return [String] Path to the logfile
+      #
+      def log_file
+        @log_file ||= @options[:log_file] ? File.expand_path(@options[:log_file]) : File.join(Rails.root, 'log', "#{rails_environment}.log")
+      end
+
+      #
+      # Determines the correct log level from the given script arguments
+      # Defaults to +INFO+
+      #
+      # @return [Int] a log level from +Log4r+
+      #
+      def log_level
+        @log_level ||= "Log4r::#{@options[:log_level].upcase}".constantize
+      end
+
+      #
+      # @return [String] the currently active rails environment
+      #
+      def rails_environment
+        ENV['RAILS_ENV']
+      end
+
+      #
+      # Checks if the given environment is currently active
+      # Works like Rails.env.env?
+      #
+      # @param [String, Symbol] env
+      #   The environment name
+      #
+      # @return [Bool] +true+ if the current environment matches the given
+      def rails_environment?(env)
+        rails_environment.to_s == env.to_s
+      end
+    end
+  end
+end

data/lib/ar_mailer_revised/mailman.rb

@@ -0,0 +1,263 @@
+#
+# This class handles the actual email sending.
+# It is called by the +ar_sendmail+ executable in /bin
+# with command line arguments
+#
+# @author Stefan Exner
+#
+
+require 'net/smtp'
+require 'ar_mailer_revised/version'
+require 'ar_mailer_revised/helpers/command_line'
+require 'ar_mailer_revised/helpers/general'
+
+module ArMailerRevised
+  class Mailman
+    include ArMailerRevised::Helpers::General
+    include ArMailerRevised::Helpers::CommandLine
+
+    #
+    # Simply holds a copy of the options given in from command line
+    #
+    def initialize(options = {})
+      @options = options
+    end
+
+    def run
+     logger.debug 'ArMailerRevised initialized with the following options:'
+     logger.debug Hirb::Helpers::AutoTable.render @options
+
+     deliver_emails
+    end
+
+    private
+
+    #
+    # Performs a single email sending for the given batch size
+    # Only emails which are ready for sending are actually sent.
+    # "Ready for sending" means in this case, that +delivery_time+ is +nil+
+    # or set to a time which is <= Time.now
+    #
+    # Take a look at +EmailScaffold+ for more information
+    # about the used scopes
+    #
+    # @todo: Check if we should delete emails which cause SMTPFatalErrors
+    # @todo: Probably add better error handling than simple re-tries
+    #
+    def deliver_emails
+      total_mail_count = ArMailerRevised.email_class.ready_to_deliver.count
+      emails           = ArMailerRevised.email_class.ready_to_deliver.with_batch_size(@options[:batch_size])
+
+      if emails.empty?
+        logger.info 'No emails to be sent, existing'
+        return
+      end
+
+      logger.info "Starting batch sending process, sending #{emails.count} / #{total_mail_count} mails"
+
+      group_emails_by_settings(emails).each do |settings_hash, grouped_emails|
+        setting = OpenStruct.new(settings_hash)
+        logger.info "Using setting #{setting.address}:#{setting.port}/#{setting.user_name}"
+
+        smtp = Net::SMTP.new(setting.address, setting.port)
+        smtp.open_timeout = 10
+        smtp.read_timeout = 10
+        setup_tls(smtp, setting)
+
+        #Connect to the server and handle possible errors
+        begin
+          smtp.start(setting.domain, setting.user_name, setting.password, setting.authentication) do
+            grouped_emails.each do |email|
+              send_email(smtp, email)
+            end
+          end
+        rescue Net::SMTPAuthenticationError => e
+          handle_smtp_authentication_error(setting, e, grouped_emails)
+        rescue Net::SMTPServerBusy => e
+          logger.warn 'Server is busy, trying again next batch.'
+          logger.warn 'Complete Error: ' + e.to_s
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          handle_smtp_timeout(setting, e, grouped_emails)
+        rescue Net::SMTPSyntaxError, Net::SMTPFatalError, Net::SMTPUnknownError => e
+          #TODO: Should we remove the custom SMTP settings here as well?
+          logger.warn 'Other SMTP error, trying again next batch.'
+          logger.warn 'Complete Error: ' + e.to_s
+        rescue Exception => e
+          logger.warn 'Other Error, trying again next batch.'
+          logger.warn 'Complete Error: ' + e.to_s
+          puts e.backtrace
+        end
+      end
+    end
+
+    #
+    # As there may be multiple emails using the same SMTP settings,
+    # it would just slow down the sending having to connect to the server
+    # multiple times. Therefore, all emails with the same settings
+    # are grouped together.
+    #
+    # @param [Array<Email>] emails
+    #   Emails to be grouped together
+    #
+    # @return [Hash<Setting, Email>]
+    #   Hash mapping SMTP settings to emails.
+    #   All emails which did not have custom SMTP settings are
+    #   grouped together under the default SMTP settings.
+    #
+    def group_emails_by_settings(emails)
+      emails.inject({}) do |hash, email|
+        setting = ActionMailer::Base.smtp_settings
+
+        if email.smtp_settings
+          setting = email.smtp_settings.clone
+          setting[:custom_setting] = true
+        end
+
+        hash[setting] ||= []
+        hash[setting] << email
+
+        hash
+      end
+    end
+
+    #
+    # Sets the wished TLS / StartTLS options in the
+    # given SMTP instance, based on what the user defined
+    # in his application's / the email's SMTP settings.
+    #
+    # Available Settings are (descending importance, meaning that
+    # a higher importance setting will override a lower importance setting)
+    #
+    # 1. +:enable_starttls_auto+ enables STARTTLS if the serves is capable to handle it
+    # 2. +:enable_starttls+ forces the usage of STARTTLS, whether the server is capable of it or not
+    # 3. +:tls+ forces the usage of TLS (SSL SMTP)
+    #
+    def setup_tls(smtp, setting)
+      if setting.enable_starttls_auto
+        logger.debug 'Using STARTTLS, if the server accepts it'
+        smtp.enable_starttls_auto
+      elsif setting.enable_starttls
+        logger.debug 'Forcing STARTTLS'
+        smtp.enable_starttls
+      elsif setting.tls
+        logger.debug 'Forcing TLS'
+        smtp.enable_tls
+      end
+    end
+
+    #
+    # Performs an email sending attempt
+    #
+    # @param [Net::SMTP] smtp
+    #   The SMTP connection which already has to be established
+    #
+    # @param [Email]
+    #   The email record to be sent.
+    #
+    # Error handling works as follows:
+    #
+    #   - If the server is busy while sending the email (SMTPServerBusy),
+    #     the system will leave the email at its old place in the queue and try
+    #     again next batch as we simply assume that the server failure is just temporarily
+    #     and the email will not cause the whole email sending to stagnate
+    #
+    #   - If another error occurs, the system will adjust the last_send_attempt
+    #     in the email record and therefore move it to the end of the queue to
+    #     ensure that other (working) emails are sent without being held up
+    #     in the queue by this probably malformed one.
+    #
+    # Errors are logged with the :warn level.
+    #
+    def send_email(smtp, email)
+      logger.info "Sending Email ##{email.id}"
+      smtp.send_message(email.mail, email.from, email.to)
+      email.destroy
+    rescue Net::SMTPServerBusy => e
+      logger.warn 'Server is currently busy, trying again next batch'
+      logger.warn 'Complete Error: ' + e.to_s
+    rescue Net::SMTPSyntaxError, Net::SMTPFatalError, Net::SMTPUnknownError, Net::ReadTimeout => e
+      logger.warn 'Other exception, trying again next batch: ' + e.to_s
+      adjust_last_send_attempt!(email)
+    end
+
+    #-----------------------------------------------------------------
+    #                    SMTP connection error handling
+    # These errors happen directly when connecting to the SMTP server
+    #-----------------------------------------------------------------
+
+    #
+    # Handles Net::OpenTimeout and Net::ReadTimeout occurring
+    # while connecting to an SMTP server.
+    #
+    # If the setting was a custom SMTP setting, it will be removed from
+    # all given emails - but only if it failed before.
+    # With this, each email setting gets 2 tries.
+    #
+    # @param [OpenStruct] setting
+    #   The used SMTP settings
+    #
+    # @param [Exception] exception
+    #   The exception thrown
+    #
+    # @param [Array<Email>] emails
+    #   All emails to be delivered using this system (in the current batch)
+    #
+    def handle_smtp_timeout(setting, exception, emails)
+      logger.warn "SMTP connection timeout while connecting to '#{setting.address}:#{setting.port}'"
+      logger.warn 'Complete Error: ' + exception.to_s
+
+      if setting.custom_setting
+        emails.each do |email|
+          if email.previously_attempted?
+            logger.warn 'Setting default SMTP settings for all affected emails, they will be sent next batch.'
+            remove_custom_smtp_settings!(email)
+          else
+            adjust_last_send_attempt!(email)
+          end
+        end
+      end
+    end
+
+    #
+    # Handles authentication errors occuring while connecting to an SMTP server.
+    # @see #handle_smtp_timeout
+    #
+    # The main difference is, that custom SMTP settings will be deleted directly
+    # as it isn't very likely that time will solve the error.
+    #
+    def handle_smtp_authentication_error(setting, exception, emails)
+      logger.warn "SMTP authentication error while connecting to '#{setting.host}:#{setting.port}'"
+      logger.warn 'Complete Error: ' + exception.to_s
+
+      if setting.custom_setting
+        logger.warn 'Setting default SMTP settings for all affected emails, they will be sent next batch.'
+
+        if setting.custom_setting
+          emails.each { |email| remove_custom_smtp_settings!(email) }
+        end
+      else
+        logger.error "Your application's base setting ('#{setting.host}:#{setting.port}') produced an authentication error!"
+      end
+    end
+
+    #
+    # Adjusts the last send attempt timestamp in the given
+    # email to the current time.
+    #
+    def adjust_last_send_attempt!(email)
+      logger.info "Setting last send attempt for email ##{email.id} (was: #{email.last_send_attempt})"
+      email.last_send_attempt = Time.now.to_i
+      email.save(:validate => false)
+    end
+
+    #
+    # Removes the custom smtp settings from a given email record
+    # and saves it without validations
+    #
+    def remove_custom_smtp_settings!(email)
+      logger.info "Removing custom SMTP settings (#{email.smtp_settings[:address]}:#{email.smtp_settings[:port]}) for email ##{email.id}"
+      email.smtp_settings = nil
+      email.save(:validate => false)
+    end
+  end
+end

data/lib/ar_mailer_revised/version.rb

@@ -1,3 +1,3 @@
 module ArMailerRevised
-  VERSION = '0.1'
+  VERSION = '1.0.0'
 end

data/lib/generators/ar_mailer_revised/install_generator.rb

@@ -0,0 +1,37 @@
+module ArMailerRevised
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      argument :model_name, :type => :string, :default => "Email"
+
+      def self.next_migration_number(path)
+        if @prev_migration_nr
+          @prev_migration_nr += 1
+        else
+          @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        end
+        @prev_migration_nr.to_s
+      end
+
+      desc 'Installs everything necessary'
+      def create_install
+        template 'model.rb', "app/models/#{model_name.classify.underscore}.rb"
+        migration_template 'migration.rb', "db/migrate/create_#{model_name.classify.underscore.pluralize}.rb"
+
+        initializer 'ar_mailer_revised.rb', <<INIT
+ArMailerRevised.configuration do |config|
+
+  #The model your application is using for email sending.
+  #If you created it using the ArMailerRevised generator, the below
+  #model name should already be correct.
+  config.email_class = #{model_name}
+
+end
+INIT
+      end
+    end
+  end
+end

data/{generators → lib/generators}/ar_mailer_revised/templates/model.rb

@@ -21,6 +21,7 @@
 #   Serialized Hash storing custom SMTP settings just for this email.
 #   If this value is +nil+, the system will use the default SMTP settings set up in the application
 #
+
 class <%= model_name.classify %> < ActiveRecord::Base
   #Helper methods and named scopes provided by ArMailerRevised
   include ArMailerRevised::EmailScaffold

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Rails.application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .