remailer 0.2.1 → 0.3.0

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/lib/remailer.rb

@@ -2,4 +2,5 @@ module Remailer
   # == Submodules ===========================================================
   
   autoload(:Connection, 'remailer/connection')
+  autoload(:Interpreter, 'remailer/interpreter')
 end

data/lib/remailer/connection.rb

@@ -6,46 +6,19 @@ class Remailer::Connection < EventMachine::Connection
   
   class CallbackArgumentsRequired < Exception; end
 
+  # == Submodules ===========================================================
+  
+  autoload(:SmtpInterpreter, 'remailer/connection/smtp_interpreter')
+  autoload(:Socks5Interpreter, 'remailer/connection/socks5_interpreter')
+
   # == Constants ============================================================
   
-  DEFAULT_TIMEOUT = 5
   CRLF = "\r\n".freeze
-  CRLF_LENGTH = CRLF.length
+  DEFAULT_TIMEOUT = 5
 
   SMTP_PORT = 25
   SOCKS5_PORT = 1080
   
-  SOCKS5_VERSION = 5
-
-  SOCKS5_METHOD = {
-    :no_auth => 0,
-    :gssapi => 1,
-    :username_password => 2
-  }.freeze
-  
-  SOCKS5_COMMAND = {
-    :connect => 1,
-    :bind => 2
-  }.freeze
-  
-  SOCKS5_REPLY = {
-    0 => 'Succeeded',
-    1 => 'General SOCKS server failure',
-    2 => 'Connection not allowed',
-    3 => 'Network unreachable',
-    4 => 'Host unreachable',
-    5 => 'Connection refused',
-    6 => 'TTL expired',
-    7 => 'Command not supported',
-    8 => 'Address type not supported'
-  }.freeze
-  
-  SOCKS5_ADDRESS_TYPE = {
-    :ipv4 => 1,
-    :domainname => 3,
-    :ipv6 => 4
-  }.freeze
-  
   NOTIFICATIONS = [
     :debug,
     :error,
@@ -54,10 +27,10 @@ class Remailer::Connection < EventMachine::Connection
   
   # == Properties ===========================================================
   
+  attr_accessor :remote, :max_size, :protocol, :hostname
+  attr_accessor :pipelining, :tls_support
   attr_accessor :timeout
-  attr_reader :state, :mode
   attr_accessor :options
-  attr_reader :remote, :max_size, :protocol
 
   # == Extensions ===========================================================
 
@@ -70,11 +43,24 @@ class Remailer::Connection < EventMachine::Connection
   # * require_tls => If true will fail connections to non-TLS capable
   #   servers (default is false)
   # * use_tls => Will use TLS if availble (default is true)
-  def self.open(smtp_server, options = nil)
+  # * debug => Where to send debugging output (IO or Proc)
+  # * connect => Where to send a connection notification (IO or Proc)
+  # * error => Where to send errors (IO or Proc)
+  # 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)
     options ||= { }
     options[:host] = smtp_server
     options[:port] ||= 25
-    options[:use_tls] = true unless (options.key?(:use_tls))
+
+    unless (options.key?(:use_tls))
+      options[:use_tls] = true
+    end
+
+    if (block_given?)
+      options[:connect] = block
+    end
     
     host_name = smtp_server
     host_port = options[:port]
@@ -84,21 +70,17 @@ class Remailer::Connection < EventMachine::Connection
       host_port = proxy_options[:port] || SOCKS5_PORT
     end
 
-    EventMachine.connect(host_name, host_port, self, options)
-  end
-  
-  def self.encode_data(data)
-    data.gsub(/((?:\r\n|\n)\.)/m, '\\1.')
-  end
-  
-  def self.base64(string)
-    [ string ].pack('m').chomp
-  end
-  
-  def self.encode_authentication(username, password)
-    base64("\0#{username}\0#{password}")
+    begin
+      EventMachine.connect(host_name, host_port, self, options)
+    rescue EventMachine::ConnectionError => e
+       options[:connect].is_a?(Proc) and options[:connect].call(false, e.to_s)
+       options[:debug].is_a?(Proc) and options[:debug].call(:error, e.to_s)
+       options[:error].is_a?(Proc) and options[:error].call(:connect_error, e.to_s)
+    end
   end
   
+  # Warns about supplying a Proc which does not appear to accept the required
+  # number of arguments.
   def self.warn_about_arguments(proc, range)
     unless (range.include?(proc.arity) or proc.arity == -1)
       STDERR.puts "Callback must accept #{[ range.min, range.max ].uniq.join(' to ')} arguments but accepts #{proc.arity}"
@@ -107,30 +89,42 @@ class Remailer::Connection < EventMachine::Connection
 
   # == Instance Methods =====================================================
   
+  # EventMachine will call this constructor and it is not to be called
+  # directly. Use the Remailer::Connection.open method to facilitate the
+  # correct creation of a new connection.
   def initialize(options)
     # Throwing exceptions inside this block is going to cause EventMachine
     # to malfunction in a spectacular way and hide the actual exception. To
     # allow for debugging, exceptions are dumped to STDERR as a last resort.
-    begin
-      @options = options
+    @options = options
+    @hostname = @options[:hostname] || Socket.gethostname
 
-      @options[:hostname] ||= Socket.gethostname
-      @messages = [ ]
-    
-      NOTIFICATIONS.each do |type|
-        callback = @options[type]
+    @messages = [ ]
+  
+    NOTIFICATIONS.each do |type|
+      callback = @options[type]
 
-        if (callback.is_a?(Proc))
-          self.class.warn_about_arguments(callback, (2..2))
-        end
+      if (callback.is_a?(Proc))
+        self.class.warn_about_arguments(callback, (2..2))
       end
-    
-      debug_notification(:options, @options.inspect)
-    
-      reset_timeout!
-    rescue Object => e
-      STDERR.puts "#{e.class}: #{e}"
     end
+  
+    debug_notification(:options, @options.inspect)
+  
+    reset_timeout!
+
+    if (using_proxy?)
+      use_socks5_interpreter!
+    else
+      use_smtp_interpreter!
+    end
+    
+  rescue Object => e
+    STDERR.puts "#{e.class}: #{e}"
+  end
+  
+  def use_tls?
+    !!@options[:use_tls]
   end
   
   # Returns true if the connection has advertised TLS support, or false if
@@ -181,9 +175,9 @@ class Remailer::Connection < EventMachine::Connection
     @messages << message
     
     # If the connection is ready to send...
-    if (@state == :ready)
+    if (@interpreter and @interpreter.state == :ready)
       # ...send the message right away.
-      send_queued_message!
+      after_ready
     end
   end
   
@@ -204,20 +198,12 @@ class Remailer::Connection < EventMachine::Connection
   # flagging the connection as estasblished.
   def connection_completed
     @timeout_at = nil
-    
-    if (using_proxy?)
-      enter_proxy_init_state!
-    else
-      connect_notification(true, "Connection completed")
-      @state = :connected
-      @connected = true
-    end
   end
   
   # This implements the EventMachine::Connection#unbind method to capture
   # a connection closed event.
   def unbind
-    @state = :closed
+    @interpreter = nil
     
     if (@active_message)
       if (callback = @active_message[:callback])
@@ -226,355 +212,135 @@ class Remailer::Connection < EventMachine::Connection
     end
   end
 
+  # This implements the EventMachine::Connection#receive_data method that
+  # is called each time new data is received from the socket.
   def receive_data(data)
-    # FIX: Buffer the data anyway.
-    
-    case (state)
-    when :proxy_init
-      version, method = data.unpack('CC')
-      
-      if (method == SOCKS5_METHOD[:username_password])
-        enter_proxy_authentication_state!
-      else
-        enter_proxy_connecting_state!
-      end
-    when :proxy_connecting
-      version, reply, reserved, address_type, address, port = data.unpack('CCCCNn')
-      
-      case (reply)
-      when 0
-        @state = :connected
-        @connected = true
-        connect_notification(true, "Connection completed")
-      else
-        debug(:error, "Proxy server returned error code #{reply}: #{SOCKS5_REPLY[reply]}")
-        connect_notification(false, "Proxy server returned error code #{reply}: #{SOCKS5_REPLY[reply]}")
-        close_connection
-        @state = :failed
-      end
-    when :proxy_authenticating
-      # Decode response of authentication request...
-      
-      # ...
-    else
-      # Data is received in arbitrary sized chunks, so there is no guarantee
-      # a whole line will be ready to process, or that there is only one line.
-      @buffer ||= ''
-      @buffer << data
-    
-      while (line_index = @buffer.index(CRLF))
-        if (line_index > 0)
-          receive_reply(@buffer[0, line_index])
-        end
+    reset_timeout!
 
-        @buffer = (@buffer[line_index + CRLF_LENGTH, @buffer.length] || '')
+    @buffer ||= ''
+    @buffer << data
+
+    if (@interpreter)
+      @interpreter.process(@buffer) do |reply|
+        debug_notification(:receive, "[#{@interpreter.label}] #{reply.inspect}")
       end
+    else
+      error_notification(:out_of_band, "Receiving data before a protocol has been established.")
     end
   end
 
   def post_init
-    @state = :connecting
-  
     EventMachine.add_periodic_timer(1) do
       check_for_timeouts!
     end
   end
+  
+  def state
+    @interpreter and @interpreter.state
+  end
 
-protected
   def send_line(line = '')
+    reset_timeout!
+
     send_data(line + CRLF)
 
     debug_notification(:send, line.inspect)
   end
 
-  # Returns true if the reply has been completed, or false if it is still
-  # in the process of being received.
-  def reply_complete?
-    !!@reply_complete
-  end
-  
   def resolve_hostname(hostname)
     # FIXME: Elminitate this potentially blocking call by using an async
     #        resolver if available.
     record = Socket.gethostbyname(hostname)
     
-    debug_notification(:resolved, record && record.last)
+    # FIXME: IPv6 Support here
+    debug_notification(:resolved, record && record.last.unpack('CCCC').join('.'))
 
     record and record.last
   rescue
     nil
   end
 
-  def receive_reply(reply)
-    debug_notification(:reply, reply.inspect)
-
-    return unless (reply)
-    
-    if (reply.match(/(\d+)([ \-])(.*)/))
-      reply_code = $1.to_i
-      @reply_complete = $2 != '-'
-      reply_message = $3
-      
-      debug_notification(:recv, reply)
-    end
-    
-    # The connection itself will be in a particular state.
-    case (state)
-    when :connected
-      case (reply_code)
-      when 220
-        reply_parts = reply_message.split(/\s+/)
-        @remote = reply_parts.first
-        
-        if (reply_parts.include?('ESMTP'))
-          @state = :sent_ehlo
-          @protocol = :esmtp
-          send_line("EHLO #{@options[:hostname]}")
-        else
-          @state = :sent_helo
-          @protocol = :smtp
-          send_line("HELO #{@options[:hostname]}")
-        end
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_ehlo
-      case (reply_code)
-      when 250
-        reply_parts = reply_message.split(/\s+/)
-        case (reply_parts[0].to_s.upcase)
-        when 'SIZE'
-          @max_size = reply_parts[1].to_i
-        when 'PIPELINING'
-          @pipelining = true
-        when 'STARTTLS'
-          @tls_support = true
-        end
-
-        if (@reply_complete)
-          if (@options[:use_tls])
-            send_line("STARTTLS")
-            @state = :sent_starttls
-          elsif (requires_authentication?)
-            enter_sent_auth_state!
-          else
-            enter_ready_state!
-          end
-        end
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_helo
-      case (reply_code)
-      when 250
-        enter_ready_state!
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_starttls
-      case (reply_code)
-      when 220
-        start_tls
-        
-        if (requires_authentication?)
-          enter_sent_auth_state!
-        else
-          enter_ready_state!
-        end
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_auth
-      case (reply_code)
-      when 235
-        enter_ready_state!
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_mail_from
-      case (reply_code)
-      when 250
-        @state = :sent_rcpt_to
-        send_line("RCPT TO:#{@active_message[:to]}")
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_rcpt_to
-      case (reply_code)
-      when 250
-        @state = :sent_data
-        send_line("DATA")
-        
-        @data_offset = 0
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_data
-      case (reply_code)
-      when 354
-        @state = :data_sending
-        
-        transmit_data!
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_data_content
-      send_callback(reply_code, reply_message)
-      
-      enter_ready_state!
-    when :sent_quit
-      case (reply_code)
-      when 221
-        @state = :closed
-        close_connection
-      else
-        fail_unanticipated_response!(reply_code, reply_message)
-      end
-    when :sent_reset
-      case (reply_code)
-      when 250
-        enter_ready_state!
-      end
-    end
+  def reset_timeout!
+    @timeout_at = Time.now + (@options[:timeout] || DEFAULT_TIMEOUT)
   end
   
-  def enter_proxy_init_state!
-    debug_notification(:proxy, "Initiating proxy connection through #{@options[:proxy][:host]}")
+  def check_for_timeouts!
+    return if (!@timeout_at or Time.now < @timeout_at)
 
-    socks_methods = [ ]
-    
-    if (@options[:proxy][:username])
-      socks_methods << SOCKS5_METHOD[:username_password]
+    error_notification(:timeout, "Connection timed out")
+    debug_notification(:timeout, "Connection timed out")
+    send_callback(:timeout, "Connection timed out before send could complete")
+
+    unless (@connected)
+      connect_notification(false, "Connection timed out")
     end
-    
-    send_data(
-      [
-        SOCKS5_VERSION,
-        socks_methods.length,
-        socks_methods
-      ].flatten.pack('CCC*')
-    )
 
-    @state = :proxy_init
+    close_connection
   end
   
-  def enter_proxy_connecting_state!
-    # REFACTOR: Move the resolution of the hostname to an earlier point to
-    #           avoid connecting needlessly.
-    
-    debug_notification(:proxy, "Sending proxy connection request to #{@options[:host]}:#{@options[:port]}")
-    
-    if (ip_address = resolve_hostname(@options[:host]))
-      send_data(
-        [
-          SOCKS5_VERSION,
-          SOCKS5_COMMAND[:connect],
-          0,
-          SOCKS5_ADDRESS_TYPE[:ipv4],
-          ip_address,
-          @options[:port]
-        ].pack('CCCCA4n')
-      )
-      
-      @state = :proxy_connecting
-    else
-      send_callback(:error_connecting, "Could not resolve hostname #{@options[:host]}")
-      
-      @state = :failed
-      close_connection
-    end
+  def pipelining?
+    !!@pipelining
   end
-  
-  def enter_proxy_authenticating_state!
-    debug_notification(:proxy, "Sending proxy authentication")
 
-    proxy_options = @options[:proxy]
-    username = proxy_options[:username]
-    password = proxy_options[:password]
-    
-    send_data(
-      [
-        SOCKS5_VERSION,
-        username.length,
-        username,
-        password.length,
-        password
-      ].pack('CCA*CA*')
-    )
-    
-    @state = :proxy_authenticating
+  def tls_support?
+    !!@tls_support
   end
   
-  def enter_ready_state!
-    @state = :ready
-    
-    send_queued_message!
+  def closed?
+    !!@closed
   end
   
-  def enter_sent_auth_state!
-    send_line("AUTH PLAIN #{self.class.encode_authentication(@options[:username], @options[:password])}")
-    @state = :sent_auth
+  def start_tls
+    debug_notification(:tls, "Started")
+    super
   end
   
-  def transmit_data!(chunk_size = nil)
-    data = @active_message[:data]
-    chunk_size ||= data.length
-    
-    # This chunk-based sending will work better when/if EventMachine can be
-    # configured to support 'writable' notifications on the active socket.
-    chunk = data[@data_offset, chunk_size]
-    debug_notification(:send, chunk.inspect)
-    send_data(self.class.encode_data(data))
-    @data_offset += chunk_size
-    
-    if (@data_offset >= data.length)
-      @state = :sent_data_content
+  def close_connection
+    debug_notification(:closed, "Connection closed")
+    super
+    @closed = true
+  end
 
-      # Ensure that a blank line is sent after the last bit of email content
-      # to ensure that the dot is on its own line.
-      send_line
-      send_line(".")
-    end
+  def use_socks5_interpreter!
+    @interpreter = Remailer::Connection::Socks5Interpreter.new(:delegate => self)
   end
-  
-  def reset_timeout!
-    @timeout_at = Time.now + (@options[:timeout] || DEFAULT_TIMEOUT)
+
+  def use_smtp_interpreter!
+    @interpreter = Remailer::Connection::SmtpInterpreter.new(:delegate => self)
   end
 
-  def send_queued_message!
+  def after_proxy_connected
+    use_smtp_interpreter!
+  end
+
+  def after_ready
     return if (@active_message)
     
     reset_timeout!
-      
+    
     if (@active_message = @messages.shift)
-      @state = :sent_mail_from
-      send_line("MAIL FROM:#{@active_message[:from]}")
+      if (@interpreter.state == :ready)
+        @interpreter.enter_state(:send)
+      end
     elsif (@options[:close])
       if (callback = @options[:after_complete])
         callback.call
       end
-
-      send_line("QUIT")
-      @state = :sent_quit
+      
+      @interpreter.enter_state(:quit)
     end
   end
 
-  def check_for_timeouts!
-    return if (!@timeout_at or Time.now < @timeout_at)
-
-    error_notification(:timeout, "Connection timed out")
-    debug_notification(:timeout, "Connection timed out")
-    send_callback(:timeout, "Connection timed out before send could complete")
-
-    @state = :timeout
-
-    unless (@connected)
-      connect_notification(false, "Connection timed out")
-    end
+  def after_message_sent(reply_code, reply_message)
+    send_callback(reply_code, reply_message)
 
-    close_connection
+    @active_message = nil
   end
   
+  def interpreter_entered_state(interpreter, state)
+    debug_notification(:state, "#{interpreter.label.downcase}=#{state}")
+  end
+
   def send_notification(type, code, message)
     case (callback = @options[type])
     when nil, false
@@ -588,8 +354,8 @@ protected
     end
   end
   
-  def connect_notification(code, message)
-    send_notification(:connect, code, message)
+  def connect_notification(code, message = nil)
+    send_notification(:connect, code, message || self.remote)
   end
 
   def error_notification(code, message)
@@ -612,15 +378,4 @@ protected
       end
     end
   end
-  
-  def fail_unanticipated_response!(reply_code, reply_message)
-    send_callback(reply_code, reply_message)
-    debug_notification(:error, "[#{@state}] #{reply_code} #{reply_message}")
-    error_notification(reply_code, reply_message)
-    
-    @active_message = nil
-    
-    @state = :sent_reset
-    send_line("RESET")
-  end
 end