remailer 0.4.21 → 0.5.0

data/README.rdoc

@@ -1,55 +1,55 @@
 = remailer
 
-Reactor-Ready Mailer Engine
+Client/Server Mail Networking Library for SMTP and IMAP
 
 == Overview
 
 This is an EventMachine Connection implementation of a high-performance
 asynchronous SMTP client. Although EventMachine ships with a built-in SMTP
-client, that version is limited to sending a single email per connection,
-and since establishing a connection can be the majority of the time required
+client, that version is limited to sending a single email per client,
+and since establishing a client can be the majority of the time required
 to send email, this limits throughput considerably.
 
 == Use
 
 The Remailer system consists of the Remailer::Connection class which works
-within the EventMachine environment. To use it, create a connection and then
+within the EventMachine environment. To use it, create a client and then
 make one or more requests to send email messages.
 
     EventMachine.run do
-      # Establish a connection to a particular SMTP server and send debugging
+      # Establish a client to a particular SMTP server and send debugging
       # messages to STDERR.
-      connection = Remailer::Connection.open(
+      client = Remailer::SMTP::Client.open(
         'smtp.google.com',
         :debug => STDERR
       )
       
-      # Send a single email message through the connection at the earliest
-      # opportunity. Note that the connection will need to be fully
+      # Send a single email message through the client at the earliest
+      # opportunity. Note that the client will need to be fully
       # established first and this may take upwards of ten seconds.
-      connection.send_email(
+      client.send_email(
         'from@example.net',
         'to@example.com',
         email_content
       )
 
-      # Send an additional message through the connection. This will queue up
+      # Send an additional message through the client. This will queue up
       # until the first has been transmitted.
-      connection.send_email(
+      client.send_email(
         'from@example.net',
         'to@example.com',
         email_content
       )
       
-      # Tells the connection to close out when finished.
-      connection.close_when_complete!
+      # Tells the client to close out when finished.
+      client.close_when_complete!
     end
 
 A Proc can be supplied as the :debug option to Remailer::Connection.open and
 in this case it will be called with two parameters, type and message. An
 example is given here where the information is simply dumped on STDOUT:
 
-    connection = Remailer::Connection.open(
+    client = Remailer::SMTP::Client.open(
       'smtp.google.com',
       :debug => lambda { |type, message|
         puts "#{type}> #{message.inspect}"
@@ -62,17 +62,17 @@ The types defined include:
   * :reply - Raw replies from the server
   * :options - The finalized options used to connect to the server
 
-This callback procedure can be defined or replaced after the connection is
+This callback procedure can be defined or replaced after the client is
 initialized:
 
-    connection.debug do |type, message|
+    client.debug do |type, message|
       STDERR.puts "%s> %s" % [ type, message.inspect ]
     end
     
 It's also possible to define a handler for when the message queue has been
 exhausted:
 
-    connection.after_complete do
+    client.after_complete do
       STDERR.puts "Sending complete."
     end
 
@@ -80,7 +80,7 @@ The call to send a message can also take a callback method which must receive
 one parameter that will be the numerical status code returned by the SMTP
 server. Success is defined as 250, errors vary:
 
-    connection.send_email(
+    client.send_email(
       'from@example.net',
       'to@example.com',
       email_content
@@ -90,6 +90,12 @@ server. Success is defined as 250, errors vary:
 
 A status code of nil is sent if the server timed out or the connection failed.
 
+== Tests
+
+In order to run tests, copy `test/config.example.rb` to `test/config.rb` and
+adjust as required. For obvious reasons, passwords to SMTP test accounts are
+not included in the source code of this library.
+
 == Status
 
 This software is currently experimental and is not recommended for production
@@ -98,4 +104,4 @@ release is made.
 
 == Copyright
 
-Copyright (c) 2010 Scott Tadman, The Working Group
+Copyright (c) 2010-2012 Scott Tadman, The Working Group

data/VERSION

@@ -1 +1 @@
-0.4.21
+0.5.0

data/lib/remailer.rb

@@ -1,6 +1,12 @@
 module Remailer
   # == Submodules ===========================================================
   
-  autoload(:Connection, 'remailer/connection')
+  autoload(:AbstractConnection, 'remailer/abstract_connection')
+  autoload(:Constants, 'remailer/constants')
+  autoload(:EmailAddress, 'remailer/email_address')
   autoload(:Interpreter, 'remailer/interpreter')
+  autoload(:IMAP, 'remailer/imap')
+  autoload(:SMTP, 'remailer/smtp')
+  autoload(:SOCKS5, 'remailer/socks5')
+  autoload(:Support, 'remailer/support')
 end

data/lib/remailer/{connection.rb → abstract_connection.rb}

@@ -1,23 +1,13 @@
-require 'socket'
-require 'eventmachine'
-
-class Remailer::Connection < EventMachine::Connection
+class Remailer::AbstractConnection < EventMachine::Connection
   # == Exceptions ===========================================================
   
   class CallbackArgumentsRequired < Exception; end
 
-  # == Submodules ===========================================================
-  
-  autoload(:SmtpInterpreter, 'remailer/connection/smtp_interpreter')
-  autoload(:Socks5Interpreter, 'remailer/connection/socks5_interpreter')
-
   # == Constants ============================================================
   
-  CRLF = "\r\n".freeze
-  DEFAULT_TIMEOUT = 5
+  include Remailer::Constants
 
-  SMTP_PORT = 25
-  SOCKS5_PORT = 1080
+  DEFAULT_TIMEOUT = 60
   
   NOTIFICATIONS = [
     :debug,
@@ -27,10 +17,6 @@ class Remailer::Connection < EventMachine::Connection
   
   # == Properties ===========================================================
   
-  attr_accessor :active_message
-  attr_accessor :remote, :max_size, :protocol, :hostname
-  attr_accessor :pipelining, :tls_support, :auth_support
-  attr_accessor :timeout
   attr_accessor :options
   attr_reader :error, :error_message
 
@@ -39,13 +25,18 @@ class Remailer::Connection < EventMachine::Connection
   include EventMachine::Deferrable
 
   # == Class Methods ========================================================
+  
+  # Defines the default timeout for connect operations.
+  def self.default_timeout
+    DEFAULT_TIMEOUT
+  end
 
-  # Opens a connection to a specific SMTP server. Options can be specified:
-  # * port => Numerical port number (default is 25)
+  # Opens a connection to a specific server. Options can be specified:
+  # * port => Numerical port number
   # * require_tls => If true will fail connections to non-TLS capable
   #   servers (default is false)
-  # * username => Username to authenticate with the SMTP server (optional)
-  # * password => Password to authenticate with the SMTP server (optional)
+  # * username => Username to authenticate with the server
+  # * password => Password to authenticate with the server
   # * use_tls => Will use TLS if availble (default is true)
   # * debug => Where to send debugging output (IO or Proc)
   # * connect => Where to send a connection notification (IO or Proc)
@@ -56,10 +47,10 @@ class Remailer::Connection < EventMachine::Connection
   # A block can be supplied in which case it will stand in as the :connect
   # option. The block will recieve a first argument that is the status of
   # the connection, and an optional second that is a diagnostic message.
-  def self.open(smtp_server, options = nil, &block)
+  def self.open(host, options = nil, &block)
     options ||= { }
-    options[:host] = smtp_server
-    options[:port] ||= 25
+    options[:host] = host
+    options[:port] ||= self.default_port
 
     unless (options.key?(:use_tls))
       options[:use_tls] = true
@@ -69,7 +60,7 @@ class Remailer::Connection < EventMachine::Connection
       options[:connect] = block
     end
     
-    host_name = smtp_server
+    host_name = host
     host_port = options[:port]
     
     if (proxy_options = options[:proxy])
@@ -141,8 +132,7 @@ class Remailer::Connection < EventMachine::Connection
     # allow for debugging, exceptions are dumped to STDERR as a last resort.
     @options = options
     @hostname = @options[:hostname] || Socket.gethostname
-    @timeout = @options[:timeout] || DEFAULT_TIMEOUT
-    @protocol = :smtp
+    @timeout = @options[:timeout] || self.class.default_timeout
 
     @messages = [ ]
   
@@ -158,12 +148,7 @@ class Remailer::Connection < EventMachine::Connection
   
     reset_timeout!
 
-    if (using_proxy?)
-      @connecting_to_proxy = true
-      use_socks5_interpreter!
-    else
-      use_smtp_interpreter!
-    end
+    self.after_initialize
     
   rescue Object => e
     STDERR.puts "#{e.class}: #{e}"
@@ -175,15 +160,13 @@ class Remailer::Connection < EventMachine::Connection
   end
   
   # Returns true if the connection has advertised TLS support, or false if
-  # not availble or could not be detected. This will only work with ESMTP
-  # capable servers.
+  # not availble or could not be detected.
   def tls_support?
     !!@tls_support
   end
 
   # Returns true if the connection has advertised authentication support, or
-  # false if not availble or could not be detected. This will only work with
-  # ESMTP capable servers.
+  # false if not availble or could not be detected.
   def auth_support?
     !!@auth_support
   end
@@ -200,66 +183,6 @@ class Remailer::Connection < EventMachine::Connection
     @options[:username] and !@options[:username].empty?
   end
 
-  # This is used to create a callback that will be called if no more messages
-  # are schedueld to be sent.
-  def after_complete(&block)
-    @options[:after_complete] = block
-  end
-  
-  # Closes the connection after all of the queued messages have been sent.
-  def close_when_complete!
-    @options[:close] = true
-  end
-
-  # Sends an email message through the connection at the earliest opportunity.
-  # A callback block can be supplied that will be executed when the message
-  # has been sent, an unexpected result occurred, or the send timed out.
-  def send_email(from, to, data, &block)
-    if (block_given?)
-      self.class.warn_about_arguments(block, 1..2)
-    end
-    
-    message = {
-      :from => from,
-      :to => to,
-      :data => data,
-      :callback => block
-    }
-    
-    @messages << message
-    
-    # If the connection is ready to send...
-    if (@interpreter and @interpreter.state == :ready)
-      # ...send the message right away.
-      after_ready
-    end
-  end
-
-  # Tests the validity of an email address through the connection at the
-  # earliest opportunity. A callback block can be supplied that will be
-  # executed when the address has been tested, an unexpected result occurred,
-  # or the request timed out.
-  def test_email(from, to, &block)
-    if (block_given?)
-      self.class.warn_about_arguments(block, 1..2)
-    end
-    
-    message = {
-      :from => from,
-      :to => to,
-      :test => true,
-      :callback => block
-    }
-    
-    @messages << message
-    
-    # If the connection is ready to send...
-    if (@interpreter and @interpreter.state == :ready)
-      # ...send the message right away.
-      after_ready
-    end
-  end
-  
   # Reassigns the timeout which is specified in seconds. Values equal to
   # or less than zero are ignored and a default is used instead.
   def timeout=(value)
@@ -267,14 +190,18 @@ class Remailer::Connection < EventMachine::Connection
     @timeout = DEFAULT_TIMEOUT if (@timeout <= 0)
   end
   
-  def proxy_connection_initiated
+  def proxy_connection_initiated!
     @connecting_to_proxy = false
   end
+
+  def proxy_connection_initiated?
+    !!@connecting_to_proxy
+  end
   
   # This implements the EventMachine::Connection#completed method by
   # flagging the connection as estasblished.
   def connection_completed
-    reset_timeout!
+    self.reset_timeout!
   end
   
   # This implements the EventMachine::Connection#unbind method to capture
@@ -282,24 +209,9 @@ class Remailer::Connection < EventMachine::Connection
   def unbind
     return if (@unbound)
 
-    @unbound = true
-    
-    if (@active_message)
-      debug_notification(:disconnect, "Disconnected by remote before transaction could be completed.")
-
-      if (callback = @active_message[:callback])
-        callback.call(nil)
-
-        @active_message = nil
-      end
-    elsif (@closed)
-      debug_notification(:disconnect, "Disconnected from remote.")
-    elsif (!@established)
-      error_notification(:hangup, "Disconnected from remote before fully established.")
-    else
-      debug_notification(:disconnect, "Disconnected by remote while connection was idle.")
-    end
+    self.after_unbind
 
+    @unbound = true
     @connected = false
     @timeout_at = nil
     @interpreter = nil
@@ -328,17 +240,18 @@ class Remailer::Connection < EventMachine::Connection
     else
       error_notification(:out_of_band, "Receiving data before a protocol has been established.")
     end
+    
+  rescue Object => e
+    STDERR.puts("[#{e.class}] #{e}")
   end
 
   def post_init
-    @timer = EventMachine.add_periodic_timer(1) do
-      check_for_timeouts!
-    end
+    self.set_timer!
   end
   
-  #
   def detach
-    @timer.cancel
+    self.cancel_timer!
+
     super
   end
   
@@ -392,6 +305,19 @@ class Remailer::Connection < EventMachine::Connection
     @timeout_at and (@timeout_at.to_i - Time.now.to_i)
   end
   
+  def set_timer!
+    @timer = EventMachine.add_periodic_timer(1) do
+      self.check_for_timeouts!
+    end
+  end
+  
+  def cancel_timer!
+    if (@timer)
+      @timer.cancel
+      @timer = nil
+    end
+  end
+
   # Checks for a timeout condition, and if one is detected, will close the
   # connection and send appropriate callbacks.
   def check_for_timeouts!
@@ -434,19 +360,7 @@ class Remailer::Connection < EventMachine::Connection
       end
     end
 
-    close_connection
-  end
-  
-  # Returns true if pipelining support has been detected on the connection,
-  # false otherwise.
-  def pipelining?
-    !!@pipelining
-  end
-
-  # Returns true if pipelining support has been detected on the connection,
-  # false otherwise.
-  def tls_support?
-    !!@tls_support
+    self.close_connection
   end
   
   # Returns true if the connection has been closed, false otherwise.
@@ -484,47 +398,19 @@ class Remailer::Connection < EventMachine::Connection
   end
   alias_method :close, :close_connection
 
-  # Switches to use the SOCKS5 interpreter for all subsequent communication
-  def use_socks5_interpreter!
-    @interpreter = Remailer::Connection::Socks5Interpreter.new(:delegate => self)
-  end
-
-  # Switches to use the SMTP interpreter for all subsequent communication
-  def use_smtp_interpreter!
-    @interpreter = Remailer::Connection::SmtpInterpreter.new(:delegate => self)
-  end
-
-  # Callback receiver for when the proxy connection has been completed.
-  def after_proxy_connected
-    use_smtp_interpreter!
-  end
-
   def after_ready
-    return if (@active_message)
-    
     @established = true
     
     reset_timeout!
-    
-    if (@active_message = @messages.shift)
-      if (@interpreter.state == :ready)
-        @interpreter.enter_state(:send)
-      end
-    elsif (@options[:close])
-      if (callback = @options[:after_complete])
-        callback.call
-      end
-      
-      @interpreter.enter_state(:quit)
-    end
   end
 
-  def after_message_sent(reply_code, reply_message)
-    message_callback(reply_code, reply_message)
-
-    @active_message = nil
+  # Switches to use the SOCKS5 interpreter for all subsequent communication
+  def use_socks5_interpreter!
+    @interpreter = Remailer::SOCKS5::Client::Interpreter.new(:delegate => self)
   end
   
+  # -- Callbacks and Notifications ------------------------------------------
+
   def interpreter_entered_state(interpreter, state)
     debug_notification(:state, "#{interpreter.label.downcase}=#{state}")
   end
@@ -541,6 +427,16 @@ class Remailer::Connection < EventMachine::Connection
       STDERR.puts("%s: %s" % [ code.to_s, message ])
     end
   end
+
+  # EventMachine: Enables TLS support on the connection.
+  def start_tls
+    debug_notification(:tls, "Started")
+    super
+  end
+  
+  def connected?
+    @connected
+  end
   
   def connect_notification(code, message = nil)
     @connected = code