larch 1.0.0 → 1.0.1

data/lib/larch/imap.rb

@@ -6,38 +6,29 @@ module Larch
 # required reading if you're doing anything with IMAP in Ruby:
 # http://sup.rubyforge.org
 class IMAP
-
-  # Recoverable connection errors.
-  RECOVERABLE_ERRORS = [
-    Errno::EPIPE,
-    Errno::ETIMEDOUT,
-    Net::IMAP::NoResponseError,
-    OpenSSL::SSL::SSLError
-  ]
-
-  # Regex to capture the individual fields in an IMAP fetch command.
-  REGEX_FIELDS = /([0-9A-Z\.]+\[[^\]]+\](?:<[0-9\.]+>)?|[0-9A-Z\.]+)/
-
-  # Regex to capture a Message-Id header.
-  REGEX_MESSAGE_ID = /message-id\s*:\s*(\S+)/i
+  attr_reader :conn, :options
 
   # URI format validation regex.
   REGEX_URI = URI.regexp(['imap', 'imaps'])
 
-  # Minimum time (in seconds) allowed between mailbox scans.
-  SCAN_INTERVAL = 60
-
   # Larch::IMAP::Message represents a transferable IMAP message which can be
   # passed between Larch::IMAP instances.
   Message = Struct.new(:id, :envelope, :rfc822, :flags, :internaldate)
 
   # Initializes a new Larch::IMAP instance that will connect to the specified
-  # IMAP URI and authenticate using the specified _username_ and _password_.
+  # IMAP URI.
   #
-  # The following options may also be specified:
+  # In addition to the URI, the following options may also be specified:
   #
   # [:create_mailbox]
-  #   If +true+, the specified mailbox will be created if necessary.
+  #   If +true+, mailboxes that don't already exist will be created if
+  #   necessary.
+  #
+  # [:dry_run]
+  #   If +true+, read-only operations will be performed as usual and all change
+  #   operations will be simulated, but no changes will actually be made. Note
+  #   that it's not actually possible to simulate mailbox creation, so
+  #   +:dry_run+ mode always behaves as if +:create_mailbox+ is +false+.
   #
   # [:fast_scan]
   #   If +true+, a faster but less accurate method will be used to scan
@@ -51,29 +42,36 @@ class IMAP
   #   After a recoverable error occurs, retry the operation up to this many
   #   times. Default is 3.
   #
-  def initialize(uri, username, password, options = {})
+  # [:ssl_certs]
+  #   Path to a trusted certificate bundle to use to verify server SSL
+  #   certificates. You can download a bundle of certificate authority root
+  #   certs at http://curl.haxx.se/ca/cacert.pem (it's up to you to verify that
+  #   this bundle hasn't been tampered with, however; don't trust it blindly).
+  #
+  # [:ssl_verify]
+  #   If +true+, server SSL certificates will be verified against the trusted
+  #   certificate bundle specified in +ssl_certs+. By default, server SSL
+  #   certificates are not verified.
+  #
+  def initialize(uri, options = {})
     raise ArgumentError, "not an IMAP URI: #{uri}" unless uri.is_a?(URI) || uri =~ REGEX_URI
-    raise ArgumentError, "must provide a username and password" unless username && password
     raise ArgumentError, "options must be a Hash" unless options.is_a?(Hash)
 
-    @uri      = uri.is_a?(URI) ? uri : URI(uri)
-    @username = username
-    @password = password
-    @options  = {:max_retries => 3}.merge(options)
+    @options = {:max_retries => 3, :ssl_verify => false}.merge(options)
+    @uri     = uri.is_a?(URI) ? uri : URI(uri)
 
-    @ids         = {}
-    @imap        = nil
-    @last_id     = 0
-    @last_scan   = nil
-    @message_ids = nil
-    @mutex       = Mutex.new
+    raise ArgumentError, "must provide a username and password" unless @uri.user && @uri.password
+
+    @conn      = nil
+    @mailboxes = {}
+    @mutex     = Mutex.new
 
     # Create private convenience methods (debug, info, warn, etc.) to make
     # logging easier.
     Logger::LEVELS.each_key do |level|
       IMAP.class_eval do
         define_method(level) do |msg|
-          Larch.log.log(level, "#{@username}@#{host}: #{msg}")
+          Larch.log.log(level, "#{username}@#{host}: #{msg}")
         end
 
         private level
@@ -81,120 +79,80 @@ class IMAP
     end
   end
 
-  # Appends the specified Larch::IMAP::Message to this mailbox if it doesn't
-  # already exist. Returns +true+ if the message was appended successfully,
-  # +false+ if the message already exists in the mailbox.
-  def append(message)
-    raise ArgumentError, "must provide a Larch::IMAP::Message object" unless message.is_a?(Message)
-    return false if has_message?(message)
-
-    safely do
-      @mutex.synchronize do
-        begin
-          @imap.select(mailbox)
-        rescue Net::IMAP::NoResponseError => e
-          if @options[:create_mailbox]
-            info "creating mailbox: #{mailbox}"
-            @imap.create(mailbox)
-            retry
-          end
-
-          raise
-        end
-      end
-
-      debug "appending message: #{message.id}"
-      @imap.append(mailbox, message.rfc822, message.flags, message.internaldate)
-    end
-
-    true
-  end
-  alias << append
-
   # Connects to the IMAP server and logs in if a connection hasn't already been
   # established.
   def connect
-    return if @imap
+    return if @conn
     safely {} # connect, but do nothing else
   end
 
+  # Gets the server's mailbox hierarchy delimiter.
+  def delim
+    @delim ||= safely { @conn.list('', '')[0].delim }
+  end
+
   # Closes the IMAP connection if one is currently open.
   def disconnect
-    return unless @imap
+    return unless @conn
 
-    @imap.disconnect
-    @imap = nil
+    begin
+      @conn.disconnect
+    rescue Errno::ENOTCONN => e
+      debug "#{e.class.name}: #{e.message}"
+    end
+
+    reset
 
     info "disconnected"
   end
-  synchronized :disconnect
-
-  # Iterates through Larch message ids in this mailbox, yielding each one to the
-  # provided block.
-  def each
-    ids = @mutex.synchronize do
-      unsync_scan_mailbox
-      @ids
-    end
 
-    ids.each_key {|id| yield id }
+  # Iterates through all mailboxes in the account, yielding each one as a
+  # Larch::IMAP::Mailbox instance to the given block.
+  def each_mailbox
+    update_mailboxes
+    @mailboxes.each_value {|mailbox| yield mailbox }
   end
 
-  # Gets a Net::IMAP::Envelope for the specified message id.
-  def envelope(message_id)
-    scan_mailbox
-    uid = @ids[message_id]
-
-    raise NotFoundError, "message not found: #{message_id}" if uid.nil?
-
-    debug "fetching envelope: #{message_id}"
-    imap_uid_fetch([uid], 'ENVELOPE').first.attr['ENVELOPE']
+  # Gets the IMAP hostname.
+  def host
+    @uri.host
   end
 
-  # Fetches a Larch::IMAP::Message struct representing the message with the
-  # specified Larch message id.
-  def fetch(message_id, peek = false)
-    scan_mailbox
-    uid = @ids[message_id]
-
-    raise NotFoundError, "message not found: #{message_id}" if uid.nil?
+  # Gets a Larch::IMAP::Mailbox instance representing the specified mailbox. If
+  # the mailbox doesn't exist and the <tt>:create_mailbox</tt> option is
+  # +false+, or if <tt>:create_mailbox</tt> is +true+ and mailbox creation
+  # fails, a Larch::IMAP::MailboxNotFoundError will be raised.
+  def mailbox(name, delim = '/')
+    retries = 0
 
-    debug "#{peek ? 'peeking at' : 'fetching'} message: #{message_id}"
-    data = imap_uid_fetch([uid], [(peek ? 'BODY.PEEK[]' : 'BODY[]'), 'FLAGS', 'INTERNALDATE', 'ENVELOPE']).first
+    name = name.gsub(delim, self.delim)
 
-    Message.new(message_id, data.attr['ENVELOPE'], data.attr['BODY[]'],
-        data.attr['FLAGS'], Time.parse(data.attr['INTERNALDATE']))
-  end
-  alias [] fetch
+    begin
+      @mailboxes.fetch(name) do
+        update_mailboxes
+        return @mailboxes[name] if @mailboxes.has_key?(name)
+        raise MailboxNotFoundError, "mailbox not found: #{name}"
+      end
 
-  # Returns +true+ if a message with the specified Larch <em>message_id</em>
-  # exists in this mailbox, +false+ otherwise.
-  def has_message?(message_id)
-    scan_mailbox
-    @ids.has_key?(message_id)
-  end
+    rescue MailboxNotFoundError => e
+      raise unless @options[:create_mailbox] && retries == 0
 
-  # Gets the IMAP hostname.
-  def host
-    @uri.host
-  end
+      info "creating mailbox: #{name}"
+      safely { @conn.create(name) } unless @options[:dry_run]
 
-  # Gets the number of messages in this mailbox.
-  def length
-    scan_mailbox
-    @ids.length
+      retries += 1
+      retry
+    end
   end
-  alias size length
 
-  # Gets the IMAP mailbox.
-  def mailbox
-    mb = @uri.path[1..-1]
-    mb.nil? || mb.empty? ? 'INBOX' : CGI.unescape(mb)
+  # Sends an IMAP NOOP command.
+  def noop
+    safely { @conn.noop }
   end
 
-  # Same as fetch, but doesn't mark the message as seen.
-  def peek(message_id)
-    fetch(message_id, true)
+  # Gets the IMAP password.
+  def password
+    CGI.unescape(@uri.password)
   end
 
   # Gets the IMAP port number.
@@ -202,53 +160,53 @@ class IMAP
     @uri.port || (ssl? ? 993 : 143)
   end
 
-  # Fetches message headers from the current mailbox.
-  def scan_mailbox
-    return if @last_scan && (Time.now - @last_scan) < SCAN_INTERVAL
+  # Connect if necessary, execute the given block, retry if a recoverable error
+  # occurs, die if an unrecoverable error occurs.
+  def safely
+    safe_connect
 
-    last_id = safely do
-      begin
-        @imap.examine(mailbox)
-      rescue Net::IMAP::NoResponseError => e
-        return if @options[:create_mailbox]
-        raise FatalError, "unable to open mailbox: #{e.message}"
-      end
+    retries = 0
 
-      @imap.responses['EXISTS'].last
-    end
+    begin
+      yield
 
-    @last_scan = Time.now
-    return if last_id == @last_id
+    rescue Errno::ECONNRESET,
+           Errno::ENOTCONN,
+           Errno::EPIPE,
+           Errno::ETIMEDOUT,
+           Net::IMAP::ByeResponseError,
+           OpenSSL::SSL::SSLError => e
 
-    range    = (@last_id + 1)..last_id
-    @last_id = last_id
+      raise unless (retries += 1) <= @options[:max_retries]
 
-    info "fetching message headers #{range}" <<
-        (@options[:fast_scan] ? ' (fast scan)' : '')
+      info "#{e.class.name}: #{e.message} (reconnecting)"
 
-    fields = if @options[:fast_scan]
-      ['UID', 'RFC822.SIZE', 'INTERNALDATE']
-    else
-      "(UID BODY.PEEK[HEADER.FIELDS (MESSAGE-ID)] RFC822.SIZE INTERNALDATE)"
-    end
+      reset
+      sleep 1 * retries
+      safe_connect
+      retry
 
-    imap_fetch(range, fields).each do |data|
-      id = create_id(data)
+    rescue Net::IMAP::BadResponseError,
+           Net::IMAP::NoResponseError,
+           Net::IMAP::ResponseParseError => e
 
-      unless uid = data.attr['UID']
-        error "UID not in IMAP response for message: #{id}"
-        next
-      end
+      raise unless (retries += 1) <= @options[:max_retries]
 
-      if @ids.has_key?(id) && Larch.log.level == :debug
-        envelope = imap_uid_fetch([uid], 'ENVELOPE').first.attr['ENVELOPE']
-        debug "duplicate message? #{id} (Subject: #{envelope.subject})"
-      end
+      info "#{e.class.name}: #{e.message} (will retry)"
 
-      @ids[id] = uid
+      sleep 1 * retries
+      retry
     end
+
+  rescue Larch::Error => e
+    raise
+
+  rescue Net::IMAP::Error => e
+    raise Error, "#{e.class.name}: #{e.message} (giving up)"
+
+  rescue => e
+    raise FatalError, "#{e.class.name}: #{e.message} (cannot recover)"
   end
-  synchronized :scan_mailbox
 
   # Gets the SSL status.
   def ssl?
@@ -260,111 +218,55 @@ class IMAP
     @uri.to_s
   end
 
-  private
-
-  # Creates an id suitable for uniquely identifying a specific message across
-  # servers (we hope).
-  #
-  # If the given message data includes a valid Message-Id header, then that will
-  # be used to generate an MD5 hash. Otherwise, the hash will be generated based
-  # on the message's RFC822.SIZE and INTERNALDATE.
-  def create_id(data)
-    ['RFC822.SIZE', 'INTERNALDATE'].each do |a|
-      raise FatalError, "requested data not in IMAP response: #{a}" unless data.attr[a]
-    end
-
-    if data.attr['BODY[HEADER.FIELDS (MESSAGE-ID)]'] =~ REGEX_MESSAGE_ID
-      Digest::MD5.hexdigest($1)
-    else
-      Digest::MD5.hexdigest(sprintf('%d%d', data.attr['RFC822.SIZE'],
-          Time.parse(data.attr['INTERNALDATE']).to_i))
-    end
+  # Gets the IMAP mailbox specified in the URI, or +nil+ if none.
+  def uri_mailbox
+    mb = @uri.path[1..-1]
+    mb.nil? || mb.empty? ? nil : CGI.unescape(mb)
   end
 
-  # Fetches the specified _fields_ for the specified message sequence id(s) from
-  # the IMAP server.
-  def imap_fetch(ids, fields)
-    data = safely { @imap.fetch(ids, fields) }
-
-    # If fields isn't an array, make it one.
-    fields = REGEX_FIELDS.match(fields).captures unless fields.is_a?(Array)
-
-    # Translate BODY.PEEK to BODY in fields, since that's how it'll come back in
-    # the response.
-    fields.map! {|f| f.sub(/^BODY\.PEEK\[/, 'BODY[') }
-
-    good_results = ids.respond_to?(:member?) ?
-        data.find_all {|i| ids.member?(i.seqno) && fields.all? {|f| i.attr.member?(f) }} :
-        data.find_all {|i| ids == i.seqno && fields.all? {|f| i.attr.member?(f) }}
-
-    if good_results.empty?
-      raise FatalError, "0 out of #{data.length} items in IMAP response for message(s) #{ids} contained all requested fields: #{fields.join(', ')}"
-    elsif good_results.length < data.length
-      error "IMAP server sent #{good_results.length} results in response to a request for #{data.length} messages"
-    end
-
-    good_results
+  # Gets the IMAP username.
+  def username
+    CGI.unescape(@uri.user)
   end
 
-  # Fetches the specified _fields_ for the specified UID(s) from the IMAP
-  # server.
-  def imap_uid_fetch(uids, fields)
-    data = safely { @imap.uid_fetch(uids, fields) }
-
-    # If fields isn't an array, make it one.
-    fields = REGEX_FIELDS.match(fields).captures unless fields.is_a?(Array)
-
-    # Translate BODY.PEEK to BODY in fields, since that's how it'll come back in
-    # the response.
-    fields.map! {|f| f.sub(/^BODY\.PEEK\[/, 'BODY[') }
-
-    good_results = data.find_all do |i|
-      i.attr.member?('UID') && uids.member?(i.attr['UID']) &&
-          fields.all? {|f| i.attr.member?(f) }
-    end
+  private
 
-    if good_results.empty?
-      raise FatalError, "0 out of #{data.length} items in IMAP response for message UID(s) #{uids.join(', ')} contained all requested fields: #{fields.join(', ')}"
-    elsif good_results.length < data.length
-      error "IMAP server sent #{good_results.length} results in response to a request for #{data.length} messages"
+  # Resets the connection and mailbox state.
+  def reset
+    @mutex.synchronize do
+      @conn = nil
+      @mailboxes.each_value {|mb| mb.reset }
     end
-
-    good_results
   end
 
-  # Connect if necessary, execute the given block, retry up to 3 times if a
-  # recoverable error occurs, die if an unrecoverable error occurs.
-  def safely
+  def safe_connect
+    return if @conn
+
     retries = 0
 
     begin
-      unsafe_connect unless @imap
-    rescue *RECOVERABLE_ERRORS => e
-      info "#{e.class.name}: #{e.message} (will retry)"
-      raise unless (retries += 1) <= @options[:max_retries]
+      unsafe_connect
 
-      @imap = nil
-      sleep 1 * retries
-      retry
-    end
+    rescue Errno::ECONNRESET,
+           Errno::EPIPE,
+           Errno::ETIMEDOUT,
+           OpenSSL::SSL::SSLError => e
 
-    retries = 0
+      raise unless (retries += 1) <= @options[:max_retries]
+
+      # Special check to ensure that we don't retry on OpenSSL certificate
+      # verification errors.
+      raise if e.is_a?(OpenSSL::SSL::SSLError) && e.message =~ /certificate verify failed/
 
-    begin
-      yield
-    rescue *RECOVERABLE_ERRORS => e
       info "#{e.class.name}: #{e.message} (will retry)"
-      raise unless (retries += 1) <= @options[:max_retries]
 
+      reset
       sleep 1 * retries
       retry
     end
 
-  rescue Net::IMAP::NoResponseError => e
-    raise Error, "#{e.class.name}: #{e.message} (giving up)"
-
-  rescue IOError, Net::IMAP::Error, OpenSSL::SSL::SSLError, SocketError, SystemCallError => e
-    raise FatalError, "#{e.class.name}: #{e.message} (giving up)"
+  rescue => e
+    raise FatalError, "#{e.class.name}: #{e.message} (cannot recover)"
   end
 
   def unsafe_connect
@@ -374,15 +276,18 @@ class IMAP
 
     Thread.new do
       begin
-        @imap = Net::IMAP.new(host, port, ssl?)
+        @conn = Net::IMAP.new(host, port, ssl?,
+            ssl? && @options[:ssl_verify] ? @options[:ssl_certs] : nil,
+            @options[:ssl_verify])
 
         info "connected on port #{port}" << (ssl? ? ' using SSL' : '')
 
         auth_methods = ['PLAIN']
         tried        = []
+        capability   = @conn.capability
 
         ['LOGIN', 'CRAM-MD5'].each do |method|
-          auth_methods << method if @imap.capability.include?("AUTH=#{method}")
+          auth_methods << method if capability.include?("AUTH=#{method}")
         end
 
         begin
@@ -391,9 +296,9 @@ class IMAP
           debug "authenticating using #{method}"
 
           if method == 'PLAIN'
-            @imap.login(@username, @password)
+            @conn.login(username, password)
           else
-            @imap.authenticate(method, @username, @password)
+            @conn.authenticate(method, username, password)
           end
 
           info "authenticated using #{method}"
@@ -407,12 +312,28 @@ class IMAP
 
       rescue => e
         exception = e
-        error e.message
       end
     end.join
 
     raise exception if exception
   end
+
+  def update_mailboxes
+    all        = safely { @conn.list('', '*') } || []
+    subscribed = safely { @conn.lsub('', '*') } || []
+
+    @mutex.synchronize do
+      # Remove cached mailboxes that no longer exist.
+      @mailboxes.delete_if {|k, v| !all.any?{|mb| mb.name == k}}
+
+      # Update cached mailboxes.
+      all.each do |mb|
+        @mailboxes[mb.name] ||= Mailbox.new(self, mb.name, mb.delim,
+            subscribed.any?{|s| s.name == mb.name}, mb.attr)
+      end
+    end
+  end
+
 end
 
 end

data/lib/larch/logger.rb

@@ -4,11 +4,12 @@ class Logger
   attr_reader :level, :output
 
   LEVELS = {
-    :fatal => 0,
-    :error => 1,
-    :warn  => 2,
-    :info  => 3,
-    :debug => 4
+    :fatal  => 0,
+    :error  => 1,
+    :warn   => 2,
+    :info   => 3,
+    :debug  => 4,
+    :insane => 5
   }
 
   def initialize(level = :info, output = $stdout)

data/lib/larch/version.rb

@@ -1,6 +1,6 @@
 module Larch
   APP_NAME      = 'Larch'
-  APP_VERSION   = '1.0.0'
+  APP_VERSION   = '1.0.1'
   APP_AUTHOR    = 'Ryan Grove'
   APP_EMAIL     = 'ryan@wonko.com'
   APP_URL       = 'http://github.com/rgrove/larch/'