mmailer 0.0.5 → 0.0.6

data/CHANGELOG.md

@@ -1,8 +1,15 @@
-## VERSION "0.0.5"
+## Version 0.0.6
+
+* Markdown template
+* real-time configuration of the mail queue
+* Retry logic
+* Catch errors at_exit
+
+## Version 0.0.5
 
 * Zoho set to port 465
 * display version in cli
 
-## VERSION "0.0.4"
+## Version 0.0.4
 
 * Initial release

data/LICENSE.txt

@@ -1,22 +1,10 @@
 Copyright (c) 2013 Daniel Szmulewicz
 
-MIT License
+LGPLv3 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:
+Mmailer is an Open Source project licensed under the terms of
+the LGPLv3 license.  Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
+for license text.
 
-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.
+Mmailer can be made available with a commercial-friendly license allowing private forks
+and modifications. Please mail me for inquiries: daniel.szmulewicz@gmail.com

data/README.md

@@ -5,7 +5,7 @@
 The purpose of Mmailer is to allow the sending of personalized bulk email, like a newsletter, through regular SMTP providers (for example Gmail).
 Regular SMTP providers imposes restrictions on how much mail you can send. Because various throttling strategies are used, and because they are not  always explicit, it is sometimes difficult to evaluate whether you will succeed in sending that newsletter of yours to all of your users.
 
-Mmailer is flexible, and well help you make sure you stay within those limits, whatever they may be. Mmailer is backend agnostic. Nor does it make any assumptions on data formats. It will process the objects you feed it. You can tell Mmailer to randomize the interval between the sending of emails, how long it should wait after a number of emails have been sent, pause the mail queue, resume it at will...
+Mmailer is flexible, and will help you make sure you stay within those limits, whatever they may be. Mmailer is backend agnostic. Nor does it make any assumptions on data formats. It will process the objects you feed it. You can tell Mmailer to randomize the interval between the sending of emails, how long it should wait after a number of emails have been sent, pause the mail queue, resume it at will...
 
 Is it any good?
 ---
@@ -103,33 +103,44 @@ end
 * `from`: The from address that will be used in your emails.
 * `subject`: The subject of your email.
 * `provider`: The name of your provider. These are preset. For the moment, one of `:gmail`, `:zoho` or `:mandrill`. Please add more providers via pull requests or by sending me mail.
-* `time_interval`: The number of seconds we want to wait between emails. We use this value as a ceiling when randomizing.
-* `mail_interval`: After how many emails we wait before continuing.
-* `sleep_time`: How long we wait when we reach the mail interval/threshold.
+* `time_interval`: The number of seconds we want to wait between emails. This value is randomized, and represents thus the ceiling (maximum value).
+* `mail_interval`: How many emails we want to send before sleeping (see below).
+* `sleep_time`: How long we sleep when we reach the mail interval (see above).
 * `collection`: An array of objects that respond to an `email` message. In the above example, the objects also respond to a `name` message. This will prove handy in templates. Instead of directly providing the array, it is recommended to specify a lambda that returns said array. You will then be able to make expensive calls to your database, bringing as many objects as memory permits, without impacting the server startup time.
-* `template`: The path (relative to the current directory) and filename to the ERB templates for your mail, without suffix. For example, "newsletter". This means your template files are actually "newsletter.txt.erb" and "newsletter.html.erb" in the current directory.
+* `template`: The path (relative to the current directory) and filename to the markdown/ERB template for your mail, without suffix. For example, "newsletter". This means your template file is actually "newsletter.md.erb" in the current directory.
 
 ### Templates
 
-Templates are the body of your mail. They use the ERB templating system. Each element in your collection is available from within the template. (Much like Rails passes the instance variables from the controller to the views). Based on the collection in the previous example, a sample template would look like this:
+Best practices for HTML email prescribe that you send email in both `text/html` and `text/plain`. Since it is tedious to write and maintain two formats for the same content, Mmailer uses one markdown template that is used as-is for the textual part, and converts to HTML for its sister part.
+
+Prior to the markdown conversion, your template gets compiled by ERB. Each element in your collection is available from within the template. (Much like Rails passes the instance variables from the controller to the views). Based on the collection in the previous example, a sample template
+(`newsletter.md.erb`) might look like this:
+
 
 ```ruby
-Dear <%= user.name %>
+Dear <%= user.name %>,
 
 This is my newsletter.
 
 Yours.
-
 ```
 
-And the equivalent html template.
+It will result in the following `text/html` and `text/plain` bodies.
 
 ```ruby
-<p>Dear <em><%= user.name %></em></p>
+<p>Dear John Doe,</p>
 <p>This is my newsletter.</p>
 <p>Yours.</p>
 ```
 
+```ruby
+Dear John Doe,
+
+This is my newsletter.
+
+Yours.
+```
+
 ### Environment variables
 
 Ruby can load environment variables for you. It is thus convenient to put them at the top of `config.rb`
@@ -145,6 +156,21 @@ ENV['MMAILER_ENV'] = "production"
 
 You can define multiple pairs of usernames and passwords for the predefined providers.
 
+### On-the-fly configuration
+
+Several configuration options can be changed dynamically, while the server is running.
+
+Those are:
+
+* `time_interval`: The number of seconds we want to wait between emails. This value is randomized, and represents thus the ceiling (maximum value).
+* `mail_interval`: How many emails we want to send before sleeping (see below).
+* `sleep_time`: How long we sleep when we reach the mail interval (see above).
+
+For usage instructions, type:
+
+    $ mmailer help config
+
+
 ## Real world examples
 
 ### Mongodb
@@ -169,7 +195,6 @@ Mmailer.configure do |config|
   config.subject = "My newsletter"
   config.template = "newsletter"
   config.collection = lambda { User.all.entries }
-  config.time_interval = 6
   config.from = 'John Doe <john@example.com>'
 end
 ```
@@ -200,8 +225,7 @@ total 40
 -rw-r--r--  1 daniel  1000   424 יול 14 03:43 config.rb
 -rw-r--r--  1 daniel  1000  3587 יול 10 04:08 mongo_helper.rb
 -rw-r--r--  1 daniel  1000  3027 יול 10 03:39 mongoid.yml
--rw-r--r--  1 daniel  1000    81 יול 14 03:44 newsletter.html.erb
--rw-r--r--  1 daniel  1000    60 יול 14 03:44 newsletter.txt.erb
+-rw-r--r--  1 daniel  1000    81 יול 14 03:44 newsletter.md.erb
 ```
 
 You are now ready to send your newsletter. In one terminal, type `mmailer server`, in another type `mmailer start`. Output will be displayed in the server terminal.
@@ -230,7 +254,7 @@ We used Thor to provide a command line interface.
 
 ### Web interface
 
-This program will be best served with some sort of GUI. A web-based interface (using Sinatra) is under consideration.
+This program will be best served with some sort of GUI. A web-based interface is under consideration. (Sinatra could be a good fit).
 
 ## Status
 
@@ -244,6 +268,14 @@ This is an initial release. Currently, no checks or sanitation is done when pars
 * [] Test suite
 * [] Generic template engine (Tilt, https://github.com/rtomayko/tilt)
 
+## License
+
+This software is released as open source under the LGPLv3 license. If you need a commercial license for private forks and modifications, we will provide you with a custom URL to a privately hosted gem with a commercial-friendly license. Please mail me for further inquiries.
+
+## Donations
+
+As most developers, I'm working on multiple projects in parallel. If this project is important to you, you're welcome to signal it to me by sending me a donation via paypal (or gittip). To send money via paypal, use the email address in my github profile and specify in the subject it's for mmailer. On [gittip](http://www.gittip.com/danielsz/ "Gittip"), my username is danielsz. Thank you in advance.
+
 ## Spam
 
 Mmailer is a bulk mail sending tool. Don't use it for spamming purposes. Spam is evil.

data/lib/mmailer/client.rb

@@ -0,0 +1,18 @@
+module Mmailer
+  module Client
+    def client(cmd, args=nil)
+      require 'drb/drb'
+      uri = 'druby://localhost:12345'
+      begin
+        obj = DRbObject.new_with_uri(uri)
+        if args
+          obj.send(cmd, args)
+        else
+          obj.send(cmd)
+        end
+      rescue DRb::DRbConnError => e
+        puts e.message + "\nIs the server running? (You can start the server with `mmailer server`)"
+      end
+    end
+  end
+end

data/lib/mmailer/commands.rb

@@ -1,56 +1,50 @@
+require 'mmailer/client'
+
 class MyCLI < Thor
-  desc "server", "Start server."
+  include Mmailer::Client
 
+  desc "server", "Start server."
   def server
     require 'mmailer'
     Mmailer.start_server
   end
 
   desc "start FROM", "Start an email run from FROM (default is 0, start of the collection)."
-
   def start(from=0)
     client(:start, from.to_i)
   end
 
   desc "pause", "Pause an email run."
-
   def pause
     client(:pause)
   end
 
   desc "resume", "Resume an email run."
-
   def resume
     client(:resume)
   end
 
   desc "stop", "Stop an email run and exit server."
-
   def stop
     client(:stop)
   end
 
   desc "version", "Show mmailer version"
-
   def version
-    require 'mmailer'
+    require 'mmailer/version'
     puts Mmailer::VERSION
   end
 
-  private
-
-  def client(cmd, args=nil)
-    require 'drb/drb'
-    uri = 'druby://localhost:12345'
-    begin
-      obj = DRbObject.new_with_uri(uri)
-      if args
-        obj.send(cmd, args)
-      else
-        obj.send(cmd)
-      end
-    rescue DRb::DRbConnError => e
-      puts e.message + "\nIs the server running? (You can start the server with `mmailer server`)"
+  desc "config", "Real-time mail queue configuration"
+  option :time_interval, :type => :numeric
+  option :mail_interval, :type => :numeric
+  option :sleep_time, :type => :numeric
+  def config
+    if options.empty?
+      client(:config)
+    else
+      client(:config, options)
     end
   end
+
 end

data/lib/mmailer/error_handling.rb

@@ -0,0 +1,32 @@
+module Mmailer
+  module ErrorHandling
+
+    def try(number_of_times=3)
+        retry_count = 0
+        begin
+          yield
+        rescue Net::OpenTimeout, EOFError => e
+          retry_count += 1
+          puts  "#{e.class}: #{e.message}: #{retry_count} retries"
+          sleep retry_count
+          if retry_count < number_of_times
+            retry
+          else
+            puts "Too many errors. Pausing mail queue."
+            client(:pause)
+          end
+          nil
+        rescue Net::SMTPUnknownError => e
+          puts e.message
+          client(:pause)
+        end
+    end
+
+    at_exit do
+      if $!
+        puts "We're going down: #{$!.class} \n #{$!.message} \n #{$!.backtrace}"
+      end
+    end
+
+  end
+end

data/lib/mmailer/mail_helper.rb

@@ -1,5 +1,6 @@
 module Mmailer
   class MailHelper
+    include ErrorHandling
     attr_reader :template, :subject, :from
 
     def initialize(args)
@@ -22,12 +23,14 @@ module Mmailer
       mail.from = from
       mail.subject = subject
 
+      compiled_source=ERB.new(File.read(Dir.pwd + "/" + Mmailer.configuration.template + ".md.erb")).result(binding)
+
       text_part = Mail::Part.new
-      text_part.body=ERB.new(File.read(Dir.pwd + "/" + Mmailer.configuration.template + ".txt.erb")).result(binding)
+      text_part.body=compiled_source
 
       html_part = Mail::Part.new
       html_part.content_type='text/html; charset=UTF-8'
-      html_part.body=ERB.new(File.read(Dir.pwd + "/" + Mmailer.configuration.template + ".html.erb")).result(binding)
+      html_part.body=Kramdown::Document.new(compiled_source).to_html
 
       mail.text_part = text_part
       mail.html_part = html_part
@@ -36,11 +39,11 @@ module Mmailer
 
       case ENV['MMAILER_ENV']
         when "production"
-          mail.deliver!
+          try { mail.deliver! }
         when "development"
           puts mail.to_s
         else
-          mail.deliver!
+          mail.to_s
       end
     end
   end

data/lib/mmailer/server_helper.rb

@@ -58,5 +58,16 @@ module Mmailer
       end
     end
 
+    def config(options=nil)
+      if options.nil?
+        puts "I will send emails every #{Mmailer.configuration.time_interval} seconds. After #{Mmailer.configuration.mail_interval} emails, I will sleep for #{Mmailer.configuration.sleep_time} seconds."
+      else
+        Mmailer.configuration.sleep_time = options.fetch("sleep_time", Mmailer.configuration.sleep_time)
+        Mmailer.configuration.mail_interval = options.fetch("mail_interval", Mmailer.configuration.mail_interval)
+        Mmailer.configuration.time_interval = options.fetch("time_interval", Mmailer.configuration.time_interval)
+        puts "#{options}. OK."
+      end
+    end
+
   end
 end

data/lib/mmailer/version.rb

@@ -1,3 +1,3 @@
 module Mmailer
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/lib/mmailer/worker.rb

@@ -8,24 +8,28 @@ module Mmailer
       @obj = DRbObject.new_with_uri('druby://localhost:12345')
       meta = { subject: Mmailer.configuration.subject, from:  Mmailer.configuration.from, template: Mmailer.configuration.template, provider: Mmailer.configuration.provider }
       @mailHelper = MailHelper.new(meta)
-      @time_interval = Mmailer.configuration.time_interval
-      @mail_interval = Mmailer.configuration.mail_interval
-      @sleep_time = Mmailer.configuration.sleep_time
       load_collection
       exec
     end
 
+    private
+
     def exec
       while not collection.empty? do
         case obj.state
           when :paused
             sleep 1
           when :started
+            load_config
             index ||= from; index += 1
             user = collection.shift
-            obj.puts "#{index}: #{user.email}"
-            mailHelper.send_email(user) if not user.email.nil?
-            sleep rand(time_interval)
+            if not user.email.nil?
+              obj.puts "#{index}: #{user.email}"
+              mailHelper.send_email(user)
+              sleep rand(time_interval)
+            else
+              obj.puts "#{index}: No email found. Skipping."
+            end
             if index % mail_interval == 0
               obj.puts "#{mail_interval} element, going to sleep for #{sleep_time} seconds"
               sleep sleep_time
@@ -45,5 +49,10 @@ module Mmailer
       obj.puts "Loaded #{collection.count} entries"
     end
 
+    def load_config
+      @time_interval = Mmailer.configuration.time_interval
+      @mail_interval = Mmailer.configuration.mail_interval
+      @sleep_time = Mmailer.configuration.sleep_time
+    end
   end
 end

data/lib/mmailer.rb

@@ -4,12 +4,14 @@ module Mmailer
 
   require 'mail'
   require 'micromachine'
+  require 'kramdown'
   require 'erb'
   require 'drb/drb'
   require 'mmailer/config'
   require 'mmailer/providers'
   require 'mmailer/server'
   require 'mmailer/server_helper'
+  require 'mmailer/error_handling'
   require 'mmailer/mail_helper'
   require 'mmailer/worker'
 

data/mmailer.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.description   = %q{Bulk mailer with remote control (drb server)}
   spec.summary       = %q{Bulk mailing the Ruby way}
   spec.homepage      = "https://github.com/danielsz/mmailer"
-  spec.license       = "MIT"
+  spec.license       = "LGPL.v3"
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -25,4 +25,5 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'thor'
   spec.add_runtime_dependency 'mail'
   spec.add_runtime_dependency 'micromachine'
+  spec.add_runtime_dependency 'kramdown'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mmailer
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-16 00:00:00.000000000 Z
+date: 2013-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -107,6 +107,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Bulk mailer with remote control (drb server)
 email:
 - danielsz@freeshell.org
@@ -123,8 +139,10 @@ files:
 - Rakefile
 - bin/mmailer
 - lib/mmailer.rb
+- lib/mmailer/client.rb
 - lib/mmailer/commands.rb
 - lib/mmailer/config.rb
+- lib/mmailer/error_handling.rb
 - lib/mmailer/mail_helper.rb
 - lib/mmailer/providers.rb
 - lib/mmailer/server.rb
@@ -135,7 +153,7 @@ files:
 - spec/spec_helper.rb
 homepage: https://github.com/danielsz/mmailer
 licenses:
-- MIT
+- LGPL.v3
 post_install_message: 
 rdoc_options: []
 require_paths: