remailer 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/README.rdoc

@@ -0,0 +1,87 @@
+= remailer
+
+Reactor-Ready Mailer Engine
+
+== 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
+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
+make one or more requests to send email messages.
+
+    EventMachine.run do
+      # Establish a connection to a particular SMTP server and send debugging
+      # messages to STDERR.
+      connection = Remailer::Connection.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
+      # established first and this may take upwards of ten seconds.
+      connection.send_email(
+        'from@example.net',
+        'to@example.com',
+        email_content
+      )
+
+      # Send an additional message through the connection. This will queue up
+      # until the first has been transmitted.
+      connection.send_email(
+        'from@example.net',
+        'to@example.com',
+        email_content
+      )
+      
+      # Tells the connection to close out when finished.
+      connection.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(
+      'smtp.google.com',
+      :debug => lambda { |type, message|
+        puts "#{type}> #{message.inspect}"
+      }
+    )
+    
+The types defined include:
+
+  * :send - Raw data sent by the client
+  * :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
+initialized:
+
+    connection.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
+      STDERR.puts "Sending complete."
+    end
+
+== Status
+
+This software is currently experimental and is not recommended for production
+use. Many of the internals may change significantly before a proper beta
+release is made.
+
+== Copyright
+
+Copyright (c) 2010 Scott Tadman, The Working Group

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "remailer"
+    gem.summary = %Q{Reactor-Ready SMTP Mailer}
+    gem.description = %Q{EventMachine capable SMTP engine}
+    gem.email = "scott@twg.ca"
+    gem.homepage = "http://github.com/twg/remailer"
+    gem.authors = [ "Scott Tadman" ]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :test => :check_dependencies
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/remailer.rb

@@ -0,0 +1,5 @@
+module Remailer
+  # == Submodules ===========================================================
+  
+  autoload(:Connection, 'remailer/connection')
+end

data/lib/remailer/connection.rb

@@ -0,0 +1,357 @@
+require 'socket'
+require 'eventmachine'
+
+class Remailer::Connection < EventMachine::Connection
+  # == Constants ============================================================
+  
+  DEFAULT_TIMEOUT = 5
+  SMTP_PORT = 25
+  CRLF = "\r\n".freeze
+  CRLF_LENGTH = CRLF.length
+  
+  # == Properties ===========================================================
+  
+  attr_accessor :timeout
+  attr_reader :state, :mode
+  attr_accessor :options
+  attr_reader :remote, :max_size, :protocol
+
+  # == Extensions ===========================================================
+
+  include EventMachine::Deferrable
+
+  # == Class Methods ========================================================
+
+  # Opens a connection to a specific SMTP server. Options can be specified:
+  # * port => Numerical port number (default is 25)
+  # * 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)
+    options ||= { }
+    options[:port] ||= 25
+    options[:use_tls] = true unless (options.key?(:use_tls))
+    
+    EventMachine.connect(smtp_server, options[:port], self, options)
+  end
+  
+  # EHLO address
+  # MAIL FROM:<reverse-path> [SP <mail-parameters> ] <CRLF>
+  # RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>
+  # DATA <CRLF>
+  # NOOP
+  # QUIT
+  
+  # 250-mx.google.com at your service, [99.231.152.248]
+  # 250-SIZE 35651584
+  # 250-8BITMIME
+  # 250-STARTTLS
+  # 250 ENHANCEDSTATUSCODES
+  
+  def self.encode_data(data)
+    data.gsub(/((?:\r\n|\n)\.)/m, '\\1.')
+  end
+
+  # == Instance Methods =====================================================
+  
+  def initialize(options)
+    @options = options
+
+    @options[:hostname] ||= Socket.gethostname
+    @messages = [ ]
+    
+    debug_notification(:options, @options.inspect)
+    
+    @timeout_at = Time.now + (@timeout || DEFAULT_TIMEOUT)
+  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.
+  def tls_support?
+    !!@tls_support
+  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
+  
+  def close_when_complete!
+    @options[:close] = true
+  end
+
+  def send_email(from, to, data, &block)
+    message = {
+      :from => from,
+      :to => to,
+      :data => data,
+      :callback => block
+    }
+    
+    @messages << message
+    
+    if (@state == :ready)
+      send_queued_message!
+    end
+  end
+  
+  # Returns the details of the active message being sent, or nil if no message
+  # is being sent.
+  def active_message
+    @active_message
+  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)
+    @timeout = value.to_i
+    @timeout = DEFAULT_TIMEOUT if (@timeout <= 0)
+  end
+  
+  # This implements the EventMachine::Connection#completed method by
+  # flagging the connection as estasblished.
+  def connection_completed
+    @timeout_at = nil
+    @state = :connected
+  end
+  
+  # This implements the EventMachine::Connection#unbind method to capture
+  # a connection closed event.
+  def unbind
+    @state = :closed
+    
+    if (@active_message)
+      if (callback = @active_message[:callback])
+        callback.call(nil)
+      end
+    end
+  end
+
+  def receive_data(data)
+    # 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
+
+      @buffer = (@buffer[line_index + CRLF_LENGTH, @buffer.length] || '')
+    end
+  end
+
+  def post_init
+    @state = :connecting
+  
+    EventMachine.add_periodic_timer(1) do
+      check_for_timeouts!
+    end
+  end
+
+  def send_line(line = '')
+    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 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
+    end
+    
+    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)
+      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
+      
+        # FIX: Add TLS support
+        #        if (@tls_support and @options[:use_tls])
+        #          @state = :tls_init
+        #        end
+
+        if (@reply_complete)
+          # Add authentication hook
+          @state = :ready
+
+          send_queued_message!
+        end
+      else
+        fail_unanticipated_response!(reply)
+      end
+    when :sent_helo
+      case (reply_code)
+      when 250
+        @state = :ready
+      else
+        fail_unanticipated_response!(reply)
+      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)
+      end
+    when :sent_rcpt_to
+      case (reply_code)
+      when 250
+        @state = :sent_data
+        send_line("DATA")
+        
+        @data_offset = 0
+      else
+        fail_unanticipated_response!(reply)
+      end
+    when :sent_data
+      case (reply_code)
+      when 354
+        @state = :data_sending
+        
+        transmit_data_chunk!
+      else
+        fail_unanticipated_response!(reply)
+      end
+    when :sent_data_content
+      if (callback = @active_message[:callback])
+        callback.call(reply_code)
+      end
+      
+      @state = :ready
+      
+      send_queued_message!
+    when :sent_quit
+      case (reply_code)
+      when 221
+        @state = :closed
+        close_connection
+      else
+        fail_unanticipated_response!(reply)
+      end
+    when :sent_reset
+      case (reply_code)
+      when 250
+        @state = :ready
+        
+        
+        send_queued_message!
+      end
+    end
+  end
+  
+  def transmit_data_chunk!(chunk_size = nil)
+    data = @active_message[:data]
+    chunk_size ||= data.length
+    
+    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
+
+      # 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
+  end
+  
+  def notify_writable
+    # FIXME: Get EventMachine to trigger this
+  end
+
+  def send_queued_message!
+    return if (@active_message)
+      
+    if (@active_message = @messages.shift)
+      @state = :sent_mail_from
+      send_line("MAIL FROM:#{@active_message[:from]}")
+    elsif (@options[:close])
+      if (callback = @options[:after_complete])
+        callback.call
+      end
+
+      send_line("QUIT")
+      @state = :sent_quit
+    end
+  end
+
+  def check_for_timeouts!
+    return if (!@timeout_at or Time.now < @timeout_at)
+
+    callback(nil)
+    @state = :timeout
+    close_connection
+  end
+  
+  def debug_notification(type, message)
+    case (@options[:debug])
+    when nil, false
+      # No debugging in this case
+    when Proc
+      @options[:debug].call(type, message)
+    when IO
+      @options[:debug].puts("%s: %s" % [ type, message ])
+    else
+      STDERR.puts("%s: %s" % [ type, message ])
+    end
+  end
+  
+  def fail_unanticipated_response!(reply)
+    if (@active_message)
+      if (callback = @active_message[:callback])
+        callback.call(nil)
+      end
+    end
+    
+    @active_message = nil
+    
+    @state = :sent_reset
+    send_line("RESET")
+  end
+end

data/remailer.gemspec

@@ -0,0 +1,50 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{remailer}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Scott Tadman"]
+  s.date = %q{2010-11-17}
+  s.description = %q{EventMachine capable SMTP engine}
+  s.email = %q{scott@twg.ca}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/remailer.rb",
+     "lib/remailer/connection.rb",
+     "remailer.gemspec",
+     "test/helper.rb",
+     "test/unit/remailer_test.rb"
+  ]
+  s.homepage = %q{http://github.com/twg/remailer}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Reactor-Ready SMTP Mailer}
+  s.test_files = [
+    "test/helper.rb",
+     "test/unit/remailer_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.expand_path(*%w[ .. lib ]), File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'timeout'
+require 'thwait'
+require 'rubygems'
+
+if (Gem.available?('eventmachine'))
+  gem 'eventmachine'
+  require 'eventmachine'
+else
+  raise "EventMachine gem is not installed."
+end
+
+require 'remailer'
+
+class Test::Unit::TestCase
+  def engine
+    exception = nil
+    
+    ThreadsWait.all_waits(
+      Thread.new do
+        Thread.abort_on_exception = true
+        # Create a thread for the engine to run on
+        EventMachine.run
+      end,
+      Thread.new do
+        # Execute the test code in a separate thread to avoid blocking
+        # the EventMachine loop.
+        begin
+          yield
+        rescue Object => exception
+        ensure
+          EventMachine.stop_event_loop
+        end
+      end
+    )
+    
+    if (exception)
+      raise exception
+    end
+  end
+  
+  def assert_timeout(time, message = nil, &block)
+    Timeout::timeout(time, &block)
+  rescue Timeout::Error
+    flunk(message || 'assert_timeout timed out')
+  end
+  
+  def assert_eventually(time = nil, message = nil, &block)
+    start_time = Time.now.to_i
+
+    while (!block.call)
+      select(nil, nil, nil, 0.1)
+      
+      if (time and (Time.now.to_i - start_time > time))
+        flunk(message || 'assert_eventually timed out')
+      end
+    end
+  end
+end

data/test/unit/remailer_test.rb

@@ -0,0 +1,137 @@
+require File.expand_path(File.join(*%w[ .. helper ]), File.dirname(__FILE__))
+
+class RemailerTest < Test::Unit::TestCase
+  TEST_SMTP_SERVER = 'mail.postageapp.com'.freeze
+  
+  def test_encode_data
+    sample_data = "Line 1\r\nLine 2\r\n.\r\nLine 3\r\n.Line 4\r\n"
+    
+    assert_equal "Line 1\r\nLine 2\r\n..\r\nLine 3\r\n..Line 4\r\n", Remailer::Connection.encode_data(sample_data)
+  end
+  
+  def test_connect
+    engine do
+      debug = { }
+      
+      connection = Remailer::Connection.open(
+        TEST_SMTP_SERVER,
+        :debug => STDERR
+      )
+
+      after_complete_trigger = false
+      
+      connection.close_when_complete!
+      connection.after_complete do
+        after_complete_trigger = true
+      end
+      
+      assert_equal :connecting, connection.state
+      assert !connection.error?
+
+      assert_eventually(15) do
+        connection.state == :closed
+      end
+      
+      assert_equal TEST_SMTP_SERVER, connection.remote
+      
+      assert_equal true, after_complete_trigger
+      
+      assert_equal 52428800, connection.max_size
+      assert_equal :esmtp, connection.protocol
+      assert_equal true, connection.tls_support?
+    end
+  end
+
+  def test_connect_and_send_after_start
+    engine do
+      connection = Remailer::Connection.open(
+        TEST_SMTP_SERVER,
+        :debug => STDERR
+      )
+      
+      assert_equal :connecting, connection.state
+      
+      assert_eventually(10) do
+        connection.state == :ready
+      end
+
+      result_code = nil
+      connection.send_email(
+        'remailer+test@example.postageapp.com',
+        'remailer+test@example.postageapp.com',
+        example_message
+      ) do |c|
+        result_code = c
+      end
+
+      assert_eventually(5) do
+        result_code == 250
+      end
+    end
+  end
+
+  def test_connect_and_send_dotted_message
+    engine do
+      connection = Remailer::Connection.open(
+        TEST_SMTP_SERVER,
+        :debug => STDERR
+      )
+      
+      assert_equal :connecting, connection.state
+      assert !connection.error?
+      
+      result_code = nil
+      connection.send_email(
+        'remailer+test@example.postageapp.com',
+        'remailer+test@example.postageapp.com',
+        example_message + "\r\n\.\r\nHam sandwich.\r\n"
+      ) do |c|
+        result_code = c
+      end
+      
+      assert_eventually(15) do
+        result_code == 250
+      end
+    end
+  end
+
+  def test_connect_and_long_send
+    engine do
+      connection = Remailer::Connection.open('twgmail.twg.ca')
+      
+      assert_equal :connecting, connection.state
+      assert !connection.error?
+      
+      result_code = nil
+      connection.send_email(
+        'sender@postageapp.com',
+        'remailer+test@example.postageapp.com',
+        example_message + 'a' * 100000
+      ) do |c|
+        result_code = c
+      end
+      
+      assert_eventually(15) do
+        result_code == 250
+      end
+    end
+  end
+  
+protected
+  def example_message
+    example = <<__END__
+Date: Sat, 13 Nov 2010 02:25:24 +0000
+From: sender@postageapp.com
+To: Remailer Test <remailer@twg.ca>
+Message-Id: <hfLkcIByfjYoNIxCO7DMsxBTX9svsFHikIOfAiYy@twg.ca>
+Subject: Example Subject
+Mime-Version: 1.0
+Content-Type: text/plain
+Auto-Submitted: auto-generated
+
+This is a very boring message. It is dreadfully dull.
+__END__
+
+    example.gsub(/\n/, "\r\n")
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: remailer
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Scott Tadman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-17 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: EventMachine capable SMTP engine
+email: scott@twg.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/remailer.rb
+- lib/remailer/connection.rb
+- remailer.gemspec
+- test/helper.rb
+- test/unit/remailer_test.rb
+has_rdoc: true
+homepage: http://github.com/twg/remailer
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Reactor-Ready SMTP Mailer
+test_files: 
+- test/helper.rb
+- test/unit/remailer_test.rb