kelredd-mailer 0.1.0

data/README.rdoc

@@ -0,0 +1,112 @@
+= Mailer
+
+== Description
+
+This is just a little gem to let you configure and send email using TMail over Net:SMTP.
+
+== Installation
+
+    sudo gem install kelredd-mailer --source http://gemcutter.org
+
+== Usage Examples
+
+=== A simple configuration
+
+    require 'mailer'
+    
+    Mailer.configure do |config|
+      config.smtp_server = "smtp.gmail.com"
+      config.smtp_helo_domain = "example.com"
+      config.smtp_port = 587
+      config.smtp_username = "test@example.com"
+      config.smtp_password = 'secret'
+      config.environment = Mailer.production  # not required, default is Mailer.development
+    end
+    
+    Mailer.send(:to => "you@example.com", :subject => "a message for you") do
+      "here is a message for you"
+    end
+    
+
+=== A more complex configuration
+  
+    # Note: this is showing a more complex configuration
+    # only setup or configure what you need or want to
+
+    require 'mailer'
+    
+    Mailer.configure do |config|
+      config.smtp_server = "smtp.gmail.com"
+      config.smtp_helo_domain = "example.com"
+      config.smtp_port = 587
+      config.smtp_username = "test@example.com"
+      config.smtp_password = 'secret'
+      
+      config.environment = Mailer.production  # not required, default is Mailer.development
+      config.smtp_auth_type = "plain"         # not required, default is "login"
+      config.default_from = "me@example.com"  # not required, default is config.smtp_username
+                                              # if it is a valid email address
+
+      config.log_file = "log/email.log"       # not required: setup a file to log mails to
+    end
+    
+    # send mails with the configured mailer...
+    # note: only requires :from (if no config.default_from), :to, and :subject
+    Mailer.send({
+      :from => 'bob@example.com',                      # not required, defaults to config.default_from
+      :reply_to => 'bob@me.com',                       # not required
+      :to => "you@example.com",
+      :cc => "Al <another@example.com>",               # send with specific naming
+      :bcc => ["one@example.com", "two@example.com"],  # send to multiple addresses
+      :subject => "a message"
+    }) do
+      # not required, don't pass .send a block if you don't want your mail to have a body
+      "a message body"
+    end
+    
+== Testing
+Mailer has some helpers and Shoulda macros to ease testing that emails were delivered with the correct parameters, fields, and content.
+
+Note: This testing only tests that mail objects were built successfully and passed all checks for delivery.  This does not actually send the mails or test sending the mails at the Net::SMTP level.
+
+=== Helpers
+In test_helper.rb or wherever:
+
+    require 'mailer/test_helpers'
+    include Mailer::TestHelpers
+  
+=== Shoulda Macros
+In test_helper.rb or wherever:
+    
+    require 'mailer/shoulda_macros/test_unit'
+    
+=== Notes / TODOs
+
+It's only live testing and known to be working with SMTP servers requiring TLS (ala Gmail).  I want to extend it to support some auth configuration and switching so that it works with SMTP, SMTPS, and SMTP/TLS.
+
+Right now, the Mailer can only have one configuration.  Maybe like to extend it to create instances of Mailers with different configurations?
+
+== License
+
+Copyright (c) 2009 Kelly Redding
+
+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:
+
+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.

data/Rakefile

@@ -0,0 +1,67 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/mailer/version'
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'kelredd-mailer'
+  s.version          = Mailer::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  s.summary          = "This gem is just a simple mailer interface."
+  s.author           = 'Kelly Redding'
+  s.email            = 'kelly@kelredd.com'
+  s.homepage         = 'http://github.com/kelredd/mailer'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib}/**/*")
+  # s.executables    = ['mailer']
+  
+  s.add_dependency('log4r')
+  s.add_dependency('tmail', '>= 1.2.3.0')
+
+  # to run the test suite, you will need this as well
+  #s.add_dependency('kelredd-useful', '>= 0.2.0')  # gem install kelredd-useful --source http://gemcutter.org
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new(:coverage) do |t|
+    t.libs       = ['test']
+    t.test_files = FileList["test/**/*_test.rb"]
+    t.verbose    = true
+    t.rcov_opts  = ['--text-report', "-x #{Gem.path}", '-x /Library/Ruby', '-x /usr/lib/ruby']
+  end
+  
+  task :default => :coverage
+  
+rescue LoadError
+  warn "\n**** Install rcov (sudo gem install relevance-rcov) to get coverage stats ****\n"
+  task :default => :test
+end
+
+
+desc 'Generate the gemspec to serve this gem'
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end
+
+require 'cucumber'
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = "test/features --format pretty" 
+end

data/lib/mailer/config.rb

@@ -0,0 +1,51 @@
+require 'mailer/exceptions'
+
+module Mailer
+  class Config
+
+    # TODO: look into abstracting port settings better based on server access type
+    # => ie, TLS or SSL or whatever
+    CONFIGS = [:smtp_helo_domain, :smtp_server, :smtp_port, :smtp_username, :smtp_password, :smtp_auth_type, :environment, :default_from]
+    NOT_REQUIRED = [:default_from]
+    CONFIGS.each do |config|
+      attr_accessor config
+    end
+    attr_reader :logger
+    
+    def initialize()
+      @logger = Log4r::Logger.new("[mailer]")
+      @logger.add(Log4r::StdoutOutputter.new('console'))
+
+      @smtp_auth_type ||= :login
+      @environment ||= Mailer::ENVIRONMENT[:development]
+    end
+    
+    def smtp_username=(value)
+      if @default_from.nil? && value && !value.match(/\A([\w\.\-\+]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i).nil?
+        @default_from = value
+      end
+      @smtp_username = value
+    end
+    
+    def log_file=(file)
+      @logger.add(Log4r::FileOutputter.new('fileOutputter', :filename => file, :trunc => false, :formatter => Log4r::PatternFormatter.new(:pattern => "[%l] %d :: %m"))) #rescue nil
+    end
+    
+    def check
+      CONFIGS.reject{|c| NOT_REQUIRED.include?(c)}.each do |config|
+        raise Mailer::ConfigError, "#{config} not configured." unless instance_variable_get("@#{config}")
+      end
+    end
+    
+    def development?
+      environment.to_s == Mailer::ENVIRONMENT[:development]
+    end
+    def test?
+      environment.to_s == Mailer::ENVIRONMENT[:test]
+    end
+    def production?
+      environment.to_s == Mailer::ENVIRONMENT[:production]
+    end
+    
+  end
+end

data/lib/mailer/deliveries.rb

@@ -0,0 +1,14 @@
+require 'mailer/exceptions'
+
+# This is just an array of sent tmail Mail objs that Mailer puts sent mails into in test mode
+module Mailer
+  class Deliveries < ::Array
+
+    def initialize(*args)
+      super(args)
+    end
+    
+    alias_method :latest, :last
+        
+  end
+end

data/lib/mailer/exceptions.rb

@@ -0,0 +1,12 @@
+module Mailer
+
+  class MailerError < StandardError
+  end
+  
+  class ConfigError < MailerError
+  end
+  
+  class SendError < MailerError
+  end
+
+end

data/lib/mailer/shoulda_macros/test_unit.rb

@@ -0,0 +1,90 @@
+module Mailer; end
+module Mailer::ShouldaMacros; end
+
+module Mailer::ShouldaMacros::TestUnit
+  
+  protected
+
+  def should_be_sent_from(*addresses)
+    addresses.flatten.each do |address|
+      should "should be sent from #{address}" do
+        assert(subject.from.include?(address), "mail not sent from #{address}")
+      end
+    end
+  end
+    
+  def should_be_sent_with_reply_to(*addresses)
+    addresses.flatten.each do |address|
+      should "should be sent with reply to #{address}" do
+        assert(subject.reply_to.include?(address), "mail not sent with reply to #{address}")
+      end
+    end
+  end
+    
+  def should_be_sent_to(*addresses)
+    addresses.flatten.each do |address|
+      should "should be sent to #{address}" do
+        assert(subject.to.include?(address), "mail not sent to #{address}")
+      end
+    end
+  end
+    
+  def should_be_sent_cc(*addresses)
+    addresses.flatten.each do |address|
+      should "should be sent cc #{address}" do
+        assert(subject.cc.include?(address), "mail not sent cc #{address}")
+      end
+    end
+  end
+    
+  def should_be_sent_bcc(*addresses)
+    addresses.flatten.each do |address|
+      should "should be sent bcc #{address}" do
+        assert(subject.bcc.include?(address), "mail not sent bcc #{address}")
+      end
+    end
+  end
+    
+  def should_be_sent_with_subject(string)
+    should "should be sent with the subject '#{string}'" do
+      assert_equal(string, subject.subject, "mail not sent with the subject '#{string}'")
+    end
+  end
+    
+  def should_be_sent_with_subject_containing(match)
+    should "should be sent with the subject containing '#{match}'" do
+      assert_match(match, subject.subject, "mail not sent with the subject containing '#{match}'")
+    end
+  end
+    
+  def should_be_sent_with_body_containing(match)
+    should "should be sent with the body containing '#{match}'" do
+      assert_match(match, subject.body, "mail not sent with the body containing '#{match}'")
+    end
+  end
+    
+  def should_be_sent_with_content_type(string)
+    should "should be sent with the content type '#{string}'" do
+      assert_equal(string, subject.content_type, "mail not sent with the content type '#{string}'")
+    end
+  end
+  
+  def should_send_mail_with_the_settings
+    should "send mail with the settings: #{subject.inspect}" do
+      assert_nothing_raised("error while sending with settings: #{subject.inspect}") do
+        Mailer.send(subject)
+      end
+    end
+  end
+    
+  def should_not_pass_the_config_check
+    should "not pass the config check" do
+      assert_raises(Mailer::ConfigError) do
+        Mailer.config.check
+      end
+    end
+  end
+  
+end
+
+Test::Unit::TestCase.extend(Mailer::ShouldaMacros::TestUnit) if defined? Test::Unit::TestCase

data/lib/mailer/test_helpers.rb

@@ -0,0 +1,9 @@
+module Mailer; end
+
+module Mailer::TestHelpers
+  
+  def latest_sent_mail
+    Mailer.deliveries.latest
+  end
+  
+end

data/lib/mailer/tls.rb

@@ -0,0 +1,73 @@
+# Note: This is a complete rip of http://github.com/ambethia/smtp-tls/tree/master
+# => I chose to copy the source in here instead of add yet another gem depencency
+# => I take no credit for this work, check out the link for more info.
+
+require 'net/smtp'
+
+Net::SMTP.class_eval do
+  private
+  def do_start(helodomain, user, secret, authtype)
+    raise IOError, 'SMTP session already started' if @started
+    
+    if RUBY_VERSION > "1.8.6"
+      check_auth_args user, secret if user or secret
+    else
+      check_auth_args user, secret, authtype if user or secret
+    end
+ 
+    sock = timeout(@open_timeout) { TCPSocket.open(@address, @port) }
+    @socket = Net::InternetMessageIO.new(sock)
+    @socket.read_timeout = 60 #@read_timeout
+ 
+    check_response(critical { recv_response() })
+    do_helo(helodomain)
+ 
+    if starttls
+      raise 'openssl library not installed' unless defined?(OpenSSL)
+      ssl = OpenSSL::SSL::SSLSocket.new(sock)
+      ssl.sync_close = true
+      ssl.connect
+      @socket = Net::InternetMessageIO.new(ssl)
+      @socket.read_timeout = 60 #@read_timeout
+      do_helo(helodomain)
+    end
+ 
+    authenticate user, secret, authtype if user
+    @started = true
+  ensure
+    unless @started
+      # authentication failed, cancel connection.
+      @socket.close if not @started and @socket and not @socket.closed?
+      @socket = nil
+    end
+  end
+ 
+  def do_helo(helodomain)
+    begin
+      if @esmtp
+        ehlo helodomain
+      else
+        helo helodomain
+      end
+    rescue Net::ProtocolError
+      if @esmtp
+        @esmtp = false
+        @error_occured = false
+        retry
+      end
+      raise
+    end
+  end
+ 
+  def starttls
+    getok('STARTTLS') rescue return false
+  return true
+  end
+ 
+  def quit
+    begin
+      getok('QUIT')
+    rescue EOFError
+    end
+  end
+end

data/lib/mailer/version.rb

@@ -0,0 +1,13 @@
+module Mailer
+  module Version
+    
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    
+    def self.to_s # :nodoc:
+      [MAJOR, MINOR, TINY].join('.')
+    end
+    
+  end
+end

data/lib/mailer.rb

@@ -0,0 +1,143 @@
+require 'openssl'
+require 'net/smtp'
+require 'tmail'
+require 'log4r'
+
+require 'mailer/exceptions'
+require 'mailer/config'
+require 'mailer/deliveries'
+require 'mailer/tls'
+
+module Mailer
+  
+  REQUIRED_FIELDS = [:from, :subject]
+  ADDRESS_FIELDS = [:to, :cc, :bcc]
+  DEFAULT_CONTENT_TYPE = "text/plain"
+  DEFAULT_CHARSET = "UTF-8"
+  
+  ENVIRONMENT = {
+    :development => 'development',
+    :test => 'test',
+    :production => 'production'
+  }
+  def self.development
+    ENVIRONMENT[:development]
+  end
+  def self.test
+    ENVIRONMENT[:test]
+  end
+  def self.production
+    ENVIRONMENT[:production]
+  end
+  
+  @@config ||= Mailer::Config.new
+  def self.configure
+    yield @@config
+  end
+  def self.config
+    @@config
+  end
+  
+  @@deliveries ||= Mailer::Deliveries.new
+  def self.deliveries
+    @@deliveries
+  end
+  
+  # Macro style helper for sending email based on the Mailer configuration
+  def self.send(settings={})
+    mail = build_tmail(settings)
+    mail.body = yield(mail) if block_given?
+    mail.body ||= ''
+    deliver_tmail(mail)
+    mail
+  end
+
+  # Returns a tmail Mail obj based on a hash of settings
+  # => same settings that the .send macro accepts
+  def self.build_tmail(some_settings)
+    settings = some_settings.dup
+    settings[:from] ||= @@config.default_from
+    mail = TMail::Mail.new
+
+    # Defaulted settings
+    mail.date = Time.now
+    mail.content_type = DEFAULT_CONTENT_TYPE
+    mail.charset = DEFAULT_CHARSET
+
+    # Required settings
+    REQUIRED_FIELDS.each {|field| mail.send("#{field}=", settings.delete(field))}
+
+    # Optional settings
+    # => settings "pass thru" to the tmail Mail obj
+    settings.each do |field, value|
+      mail.send("#{field}=", value) if mail.respond_to?("#{field}=")
+    end
+
+    mail
+  end
+  
+  # Deliver a tmail Mail obj depending on configured environment
+  # => production?: using Net::SMTP
+  # => test?: add to deliveries cache
+  # => development?: log mail
+  def self.deliver_tmail(mail)
+    check_mail(mail)
+    @@config.check
+    if @@config.production?
+      smtp_start_args = [
+        @@config.smtp_server,
+        @@config.smtp_port,
+        @@config.smtp_helo_domain,
+        @@config.smtp_username,
+        @@config.smtp_password,
+        @@config.smtp_auth_type
+      ]
+      Net::SMTP.start(*smtp_start_args) do |smtp|
+        ADDRESS_FIELDS.each do |field|
+          if (recipients = mail.send(field))
+            recipients.each {|recipient| smtp.send_message(mail.to_s, mail.from, recipient) }
+          end
+        end
+      end
+    elsif @@config.test?
+      @@deliveries << mail
+    end
+    log(:info, "Sent '#{mail.subject}' to #{mail.to ? mail.to.join(', ') : "''"} (#{@@config.environment})")
+    log_tmail(mail)
+  end
+  
+  # Logs a tmail Mail obj delivery
+  def self.log_tmail(mail)
+    log(:debug, [
+      "",
+      "====================================================================",
+      mail.to_s,
+      "====================================================================",
+      ""
+    ].join("\n"))
+  end
+  
+  protected
+  
+  def self.check_mail(tmail)
+    raise Mailer::SendError, "cannot send, bad mail object given." unless tmail && tmail.kind_of?(TMail::Mail)
+    REQUIRED_FIELDS.each do |field|
+      raise Mailer::SendError, "cannot send, #{field} not specified." unless tmail.send(field)
+    end
+    # be sure at least one of ADDRESS_FIELDS exists
+    unless ADDRESS_FIELDS.inject(false) {|exist, field| (exist || !tmail.send(field).nil?)}
+      raise Mailer::SendError, "cannot send, no #{ADDRESS_FIELDS.join('/')} specified."
+    end
+  end
+  
+  def self.log(level, msg)
+    if(msg)
+      if !@@config.production? && MAILER_LOG_AS_PUTS
+        puts "[#{level.to_s.upcase}]: [mailer] #{msg}" if Mailer.config.development?
+      elsif @@config.logger && @@config.logger.respond_to?(level)
+        @@config.logger.send(level.to_s, msg) 
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: kelredd-mailer
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Kelly Redding
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-06 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: log4r
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: tmail
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3.0
+    version: 
+description: 
+email: kelly@kelredd.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/mailer/config.rb
+- lib/mailer/deliveries.rb
+- lib/mailer/exceptions.rb
+- lib/mailer/shoulda_macros/test_unit.rb
+- lib/mailer/test_helpers.rb
+- lib/mailer/tls.rb
+- lib/mailer/version.rb
+- lib/mailer.rb
+has_rdoc: true
+homepage: http://github.com/kelredd/mailer
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: This gem is just a simple mailer interface.
+test_files: []
+