tuktuk 0.4.6 → 0.5.0

data/README.md

@@ -10,54 +10,83 @@ response status codes -- like bounces, 5xx -- within your application.
 Plus, it supports DKIM out of the box.
 
 ``` ruby
-  require 'tuktuk'
+require 'tuktuk'
 
-  email = {
-    :from => 'you@username.com',
-    :to => 'user@yoursite.com',
-    :body => 'Hello there',
-    :subject => 'Hiya'
-  }
+message = {
+  :from => 'you@username.com',
+  :to => 'user@yoursite.com',
+  :body => 'Hello there',
+  :subject => 'Hiya'
+}
 
-  Tuktuk.deliver(email)
+response, email = Tuktuk.deliver(message)
 ```
 
-To enable DKIM:
+The `response` is either a Net::SMTP::Response object, or a Bounce exception (HardBounce or SoftBounce, depending on the cause). `email` is a [mail](https://github.com/mikel/mail) object. So, to handle bounces you'd do:
 
 ``` ruby
-  require 'tuktuk'
-
-  Tuktuk.options = {
-    :dkim => {
-      :domain => 'yoursite.com',
-      :selector => 'mailer',
-      :private_key => IO.read('ssl/yoursite.com.key')
-    }
-  }
+[...]
 
-  email = {
-    :from => 'you@username.com',
-    :to => 'user@yoursite.com',
-    :body => 'Hello there',
-    :subject => 'Hiya'
-  }
+response, email = Tuktuk.deliver(message)
 
-  Tuktuk.deliver(email)
+if response.is_a?(Bounce)
+  puts 'Email bounced. Type: ' + response.class.name # => HardBounce or SoftBounce
+else
+  puts 'Email delivered!'
+end
 ```
 
-Additional options:
+With Tuktuk, you can also deliver multiple messages at once. Depending on the max_workers config parameter, Tuktuk will either connect sequentially to the target MX servers, or do it in parallel by spawning threads. You need to pass an array of emails, and you'll receive an array of [response, email] elements, just as above.
 
 ``` ruby
-  Tuktuk.options = {
-    :log_to => 'log/mailer.log',
-    :max_attempts => 5,
-    :retry_sleep => 10,
-    :dkim => { ... }
+messages = [ { ... }, { ... }, { ... }, { ... } ] # array of messages
+
+result = Tuktuk.deliver_many(messages)
+
+result.each do |response, email|
+
+  if response.is_a?(Bounce)
+    puts 'Email bounced. Type: ' + response.class.name
+  else
+    puts 'Email delivered!'
+  end
+
+end
+```
+
+Now, if you want to enable DKIM (and you should):
+
+``` ruby
+require 'tuktuk'
+
+Tuktuk.options = {
+  :dkim => {
+    :domain => 'yoursite.com',
+    :selector => 'mailer',
+    :private_key => IO.read('ssl/yoursite.com.key')
   }
+}
+
+message = { ... }
+
+response, email = Tuktuk.deliver(message)
+```
+
+For DKIM to work, you need to set up a TXT record in your domain's DNS.
+
+Additional Tuktuk options:
+
+``` ruby
+Tuktuk.options = {
+  :log_to => 'log/mailer.log',
+  :helo_domain => 'mydomain.com',
+  :max_workers => 'auto', # spawns a new thread for each domain 
+  :dkim => { ... }
+}
 ```
 
 That's all.
 
 --
 
-(c) 2012 Fork Limited. MIT license.
+(c) 2013 Fork Limited. MIT license.

data/lib/tuktuk/bounce.rb

@@ -0,0 +1,32 @@
+class Bounce < RuntimeError
+
+  HARD_BOUNCE_CODES = [
+	  501, # Bad address syntax (eg. "i.user.@hotmail.com")
+	  504, # mailbox is disabled
+    511, # sorry, no mailbox here by that name (#5.1.1 - chkuser)
+    540, # recipient's email account has been suspended.
+    550, # Requested action not taken: mailbox unavailable
+    552, # Spam Message Rejected -- Requested mail action aborted: exceeded storage allocation
+    554, # Recipient address rejected: Policy Rejection- Abuse. Go away -- This user doesn't have a yahoo.com account
+    563, # ERR_MSG_REJECT_BLACKLIST, message has blacklisted content and thus I reject it
+    571  # Delivery not authorized, message refused
+  ]
+
+  def self.type(e)
+    if e.is_a?(Net::SMTPFatalError) and code = e.to_s[0..2] and HARD_BOUNCE_CODES.include? code.to_i
+      HardBounce.new(e)
+    else
+      SoftBounce.new(e) # either soft mailbox bounce or server bounce
+    end
+  end
+
+  def code
+		if str = to_s[0..2] and str.gsub(/[^0-9]/, '') != ''
+			str.to_i
+		end
+	end
+
+end
+
+class HardBounce < Bounce; end
+class SoftBounce < Bounce; end

data/lib/tuktuk/tuktuk.rb

@@ -3,25 +3,20 @@ require 'dkim'
 require 'logger'
 require 'work_queue'
 
-%w(package cache dns).each { |lib| require "tuktuk/#{lib}" }
+%w(package cache dns bounce).each { |lib| require "tuktuk/#{lib}" }
 require 'tuktuk/version' unless defined?(Tuktuk::VERSION)
 
 DEFAULTS = {
-  :retry_sleep  => 10,
-  :max_attempts => 3,
+  :helo_domain  => nil,
   :max_workers  => 0,
   :read_timeout => 20,
   :open_timeout => 20,
-  :helo_domain  => nil,
   :verify_ssl   => true,
   :log_to       => nil # $stdout,
 }
 
 module Tuktuk
 
-  class DNSError < RuntimeError; end
-  class MissingFieldsError < ArgumentError; end
-
   class << self
 
     def cache
@@ -29,7 +24,7 @@ module Tuktuk
     end
 
     def deliver(message, opts = {})
-      raise 'Please pass a valid message object.' unless messages.is_a?(Hash)
+      raise 'Please pass a valid message object.' unless messages[:to]
       self.options = opts if opts.any?
       mail = Package.new(message)
       response = lookup_and_deliver(mail)
@@ -37,7 +32,7 @@ module Tuktuk
     end
 
     def deliver_many(messages, opts = {})
-      raise 'Please pass an array of messages.' unless messages.is_a?(Array) and messages.any?
+      raise 'Please pass an array of messages.' unless messages.any?
       self.options = opts if opts.any?
       messages_by_domain = reorder_by_domain(messages)
       lookup_and_deliver_many(messages_by_domain)
@@ -70,21 +65,6 @@ module Tuktuk
       @logger ||= Logger.new(config[:log_to])
     end
 
-    def success(to)
-      logger.info("#{to} - Successfully sent!")
-    end
-
-    def error(mail, to, error, attempt)
-      if attempt < config[:max_attempts] and (error.is_a?(EOFError) || error.is_a?(Timeout::Error))
-        logger.info "#{to} - Got #{error.class.name} error. Retrying after #{config[:retry_sleep]} secs..."
-        sleep config[:retry_sleep]
-        lookup_and_deliver(mail, attempt+1)
-      else
-        logger.error("#{to} - Couldn't send after #{attempt} attempts: #{error.message} [#{error.class.name}]")
-        raise error
-      end
-    end
-
     def get_domain(email_address)
       email_address && email_address.to_s[/@([a-z0-9\._-]+)/i, 1]
     end
@@ -115,15 +95,16 @@ module Tuktuk
 
     def lookup_and_deliver(mail, attempt = 1)
       if mail.destinations.empty?
-        raise MissingFieldsError, "No destinations found! You need to pass a :to field."
+        raise "No destinations found! You need to pass a :to field."
       end
 
       response = nil
       mail.destinations.each do |to|
 
         domain = get_domain(to)
-        servers = smtp_servers_for_domain(domain)
-        error(mail, to, DNSError.new("No MX records for domain #{domain}"), attempt) && next if servers.empty?
+        unless servers = smtp_servers_for_domain(domain)
+          return HardBounce.new("588 No MX records for domain #{domain}")
+        end
 
         last_error = nil
         servers.each do |server|
@@ -134,7 +115,7 @@ module Tuktuk
             last_error = e
           end
         end
-        error(mail, to, last_error, attempt) if last_error
+        return Bounce.type(last_error) if last_error
       end
       response
     end
@@ -187,7 +168,7 @@ module Tuktuk
       total = mails.count
 
       unless servers = smtp_servers_for_domain(domain)
-        err = DNSError.new("No MX Records for domain #{domain}")
+        err = HardBounce.new("588 No MX Records for domain #{domain}")
         mails.each { |mail| responses.push [err, mail] }
         return responses
       end
@@ -197,13 +178,15 @@ module Tuktuk
           responses.push [resp, mail]
           mails.delete(mail) # remove it from list, to avoid duplicate delivery
         end
-        logger.info "#{responses.count}/#{total} mails processed on #{domain}."
+        logger.info "#{responses.count}/#{total} mails processed on #{domain}'s MX: #{server}."
         break if responses.count == total
       end
 
       # if we still have emails in queue, mark them with the last error which prevented delivery
-      if mails.any? and @last_error 
-         mails.each { |m| responses.push [@last_error, m] }
+      if mails.any? and @last_error
+        bounce = Bounce.type(@last_error)
+        logger.info "#{mails.count} mails still pending. Marking as #{bounce.class}..."
+        mails.each { |m| responses.push [bounce, m] }
       end
 
       responses
@@ -221,14 +204,12 @@ module Tuktuk
         logger.info "#{to} - [SENT] #{response.message.strip}"
       end
 
-      success(to)
       response
     end
 
     def send_many_now(server, mails)
       logger.info "Delivering #{mails.count} mails at #{server}..."
       responses = {}
-      timeout_error = nil
 
       server = 'localhost' if ENV['DEBUG']
       socket = init_connection(server)
@@ -238,11 +219,10 @@ module Tuktuk
             resp = smtp.send_message(get_raw_mail(mail), get_from(mail), mail.to)
             smtp.send(:getok, 'RSET') if server['hotmail'] # fix for '503 Sender already specified'
           rescue Net::SMTPFatalError => e # error code 5xx, except for 500, like: 550 Mailbox not found
-            resp = e
+            resp = Bounce.type(e)
           end
           responses[mail] = resp
-          status = resp.is_a?(Net::SMTP::Response) ? 'SENT' : 'ERROR'
-          logger.info "#{mail.to} [#{status}] #{responses[mail].message.strip}" # both error and response have this method
+          logger.info "#{mail.to} [#{responses[mail].class}] #{responses[mail].message.strip}" # both error and response have this method
         end
       end
 

data/lib/tuktuk/version.rb

@@ -1,7 +1,7 @@
 module Tuktuk
   MAJOR = 0
-  MINOR = 4
-  PATCH = 6
+  MINOR = 5
+  PATCH = 0
 
   VERSION = [MAJOR, MINOR, PATCH].join('.')
 end

data/spec/deliver_spec.rb

@@ -65,14 +65,14 @@ describe 'deliver many' do
 		describe 'when delivering to domain' do
 			
 			before do
-				@mock_smtp.stub!(:start).and_yield()
+				@mock_smtp.stub(:start).and_yield('foo')
 				@emails = [email, email, email]
 
 				@success = mock('Net::SMTP::Response')
-				@soft_email_bounce = Net::SMTPFatalError.new('503 Sender already specified')
-				@hard_email_bounce = Net::SMTPFatalError.new('505 Mailbox not found')
-				@soft_server_bounce = Net::SMTPServerBusy.new('Be back in a sec')
-				@hard_server_bounce = Tuktuk::DNSError.new('No MX records found.')
+				@soft_email_bounce = SoftBounce.new('503 Sender already specified')
+				@hard_email_bounce = HardBounce.new('505 Mailbox not found')
+				@soft_server_bounce = SoftBounce.new('Be back in a sec')
+				@hard_server_bounce = HardBounce.new('No MX records found.')
 			end
 
 			describe 'when domain exists' do
@@ -85,7 +85,7 @@ describe 'deliver many' do
 					
 					before do
 						@servers = ['mx1.domain.com', 'mx2.domain.com', 'mx3.domain.com']
-						Tuktuk.stub!(:smtp_servers_for_domain).and_return(@servers)
+						Tuktuk.stub(:smtp_servers_for_domain).and_return(@servers)
 					end
 					
 					it 'starts by delivering to first one' do
@@ -130,18 +130,23 @@ describe 'deliver many' do
 					describe 'and first server is down' do
 
 						before do
-							Tuktuk.stub(:init_connection).and_return(@mock_smtp)
-							Tuktuk.stub(:init_connection).with('mx1.domain.com').and_raise('Unable to connect.')
 							@responses = []
 							@emails.each { |e| @responses.push [e, @success] }
 						end
 						
 						it 'does not raise error' do
+							Tuktuk.should_receive(:init_connection).once.with('mx1.domain.com').and_raise('Unable to connect.')
 							lambda do
 								Tuktuk.send(:lookup_and_deliver_by_domain, 'domain.com', @emails)
 							end.should_not raise_error(RuntimeError)
 						end
 
+						it 'returns empty responses' do
+							Tuktuk.should_receive(:init_connection).once.with('mx1.domain.com').and_raise('Unable to connect.')
+							responses = Tuktuk.send(:send_many_now, 'mx1.domain.com', @emails)
+							responses.should be_empty
+						end
+
 						it 'tries to connect to second server' do
 							Tuktuk.should_receive(:send_many_now).once.with('mx1.domain.com', @emails).and_return([])
 							Tuktuk.should_receive(:send_many_now).once.with('mx2.domain.com', @emails).and_return(@responses)
@@ -166,6 +171,25 @@ describe 'deliver many' do
 							Tuktuk.should_not_receive(:send_many_now).with('mx3.domain.com')
 							Tuktuk.send(:lookup_and_deliver_by_domain, 'domain.com', @emails)
 						end
+						
+						describe 'and other servers are down' do
+							
+							before do
+								# TODO: for some reason the :init_connection on line  138 is affecting this
+								# this test should pass when running on its own
+								# Tuktuk.should_receive(:init_connection).once.with('mx1.domain.com').and_return(@mock_smtp)
+								# Tuktuk.should_receive(:init_connection).once.with('mx2.domain.com').and_raise('Unable to connect.')
+								# Tuktuk.should_receive(:init_connection).once.with('mx3.domain.com').and_raise('Unable to connect.')
+							end
+							
+							it 'should not mark first email as bounced' do
+								Tuktuk.should_receive(:send_many_now).and_return([@first], [], [])
+								responses = Tuktuk.send(:lookup_and_deliver_by_domain, 'domain.com', @emails)
+								responses[1][0].should be_a(Bounce) if responses[1]
+								responses[0][0].should_not be_a(Bounce)
+							end
+							
+						end
 							
 					end
 					

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tuktuk
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -103,6 +103,7 @@ files:
 - README.md
 - Rakefile
 - lib/tuktuk.rb
+- lib/tuktuk/bounce.rb
 - lib/tuktuk/cache.rb
 - lib/tuktuk/dns.rb
 - lib/tuktuk/package.rb