larch 1.0.0 → 1.0.1

data/HISTORY

@@ -0,0 +1,23 @@
+Larch History
+================================================================================
+
+Version 1.0.1 (2009-05-10)
+  * Ruby 1.9.1 support.
+  * Much more robust handling of unexpected server disconnects and dropped
+    connections.
+  * Added --all option to copy all folders recursively.
+  * Added --all-subscribed option to copy all subscribed folders recursively.
+  * Added --dry-run option to simulate changes without actually making them.
+  * Added --exclude and --exclude-file options to specify folders that should
+    not be copied.
+  * Added --ssl-certs option to specify a bundle of trusted SSL certificates.
+  * Added --ssl-verify option to verify server SSL certificates.
+  * Added a new "insane" logging level, which will output all IMAP commands and
+    responses to STDERR.
+  * Fixed excessive post-scan processing times for very large mailboxes.
+  * Fixed potential scan problems with very large mailboxes on certain servers.
+  * POSIX signals are no longer trapped on platforms that aren't likely to
+    support them.
+
+Version 1.0.0 (2009-03-17)
+  * First release.

data/README.rdoc

@@ -0,0 +1,185 @@
+= Larch
+
+Larch is a tool to copy messages from one IMAP server to another quickly and
+safely. It's smart enough not to copy messages that already exist on the
+destination and robust enough to deal with ornery or misbehaving servers.
+
+Larch is particularly well-suited for copying email to, from, or between Gmail
+accounts.
+
+*Author*::    Ryan Grove (mailto:ryan@wonko.com)
+*Version*::   1.0.1 (2009-05-10)
+*Copyright*:: Copyright (c) 2009 Ryan Grove. All rights reserved.
+*License*::   GPL 2.0 (http://opensource.org/licenses/gpl-2.0.php)
+*Website*::   http://github.com/rgrove/larch
+
+== Installation
+
+Install Larch via RubyGems:
+
+  gem install larch
+
+== Usage
+
+  larch --from <uri> --to <uri> [options]
+
+  Required:
+       --from, -f <s>:   URI of the source IMAP server.
+         --to, -t <s>:   URI of the destination IMAP server.
+
+  Copy Options:
+                --all:   Copy all folders recursively
+     --all-subscribed:   Copy all subscribed folders recursively
+       --exclude <s+>:   List of mailbox names/patterns that shouldn't be
+                         copied
+   --exclude-file <s>:   Filename containing mailbox names/patterns that
+                         shouldn't be copied
+    --from-folder <s>:   Source folder to copy from (default: INBOX)
+      --from-pass <s>:   Source server password (default: prompt)
+      --from-user <s>:   Source server username (default: prompt)
+      --to-folder <s>:   Destination folder to copy to (default: INBOX)
+        --to-pass <s>:   Destination server password (default: prompt)
+        --to-user <s>:   Destination server username (default: prompt)
+
+  General Options:
+        --dry-run, -n:   Don't actually make any changes.
+          --fast-scan:   Use a faster (but less accurate) method to scan
+                         mailboxes. This may result in messages being
+                         re-copied.
+    --max-retries <i>:   Maximum number of times to retry after a recoverable
+                         error (default: 3)
+   --no-create-folder:   Don't create destination folders that don't already
+                         exist
+      --ssl-certs <s>:   Path to a trusted certificate bundle to use to
+                         verify server SSL certificates
+         --ssl-verify:   Verify server SSL certificates
+  --verbosity, -V <s>:   Output verbosity: debug, info, warn, error, or fatal
+                         (default: info)
+        --version, -v:   Print version and exit
+           --help, -h:   Show this message
+
+== Examples
+
+Larch is run from the command line. At a minimum, you must specify a source
+server and a destination server in the form of IMAP URIs. You may also specify
+one or more options:
+
+  larch --from <uri> --to <uri> [options]
+
+For an overview of all available command-line options, run:
+
+  larch --help
+
+Specify a source server and a destination server and Larch will prompt you for
+the necessary usernames and passwords, then sync the contents of the source's
++INBOX+ folder to the destination:
+
+  larch --from imap://mail.example.com --to imap://imap.gmail.com
+
+To <b>connect using SSL</b>, specify a URI beginning with <tt>imaps://</tt>:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com
+
+If you'd like to <b>sync a specific folder</b> other than +INBOX+, specify the
+source and destination folders using <tt>--from-folder</tt> and
+<tt>--to-folder</tt>:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com \
+    --from-folder "Sent Mail" --to-folder "Sent Mail"
+
+To <b>sync all folders</b>, use the <tt>--all</tt> option (or
+<tt>--all-subscribed</tt> if you only want to <b>sync subscribed folders</b>):
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all
+
+By default Larch will create folders on the destination server if they don't
+already exist. To prevent this, add the <tt>--no-create-folder</tt> option:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \
+    --no-create-folder
+
+You can <b>prevent Larch from syncing one or more folders</b> by using the
+<tt>--exclude</tt> option:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \
+    --exclude Spam Trash Drafts "[Gmail]/*"
+
+If your exclusion list is long or complex, create a text file with one exclusion
+pattern per line and tell Larch to load it with the <tt>--exclude-file</tt>
+option:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \
+    --exclude-file exclude.txt
+
+The wildcard characters <tt>*</tt> and <tt>?</tt> are supported in exclusion
+lists. You can also use a regular expression by enclosing a pattern in
+forward slashes, so the previous example could be achieved with the
+pattern <tt>/(Spam|Trash|Drafts|\[Gmail\]\/.*)/</tt>
+
+== Server Compatibility
+
+Larch should work well with any server that properly supports
+IMAP4rev1[http://tools.ietf.org/html/rfc3501], and does its best to get along
+with servers that have buggy, unreliable, or incomplete IMAP implementations.
+
+Larch has been tested on and is known to work well with the following IMAP
+servers:
+
+* Dovecot
+* Gmail
+* Microsoft Exchange 2003
+
+== Known Issues
+
+* Larch uses Ruby's Net::IMAP standard library for all IMAP operations. While
+  Net::IMAP is generally a very solid library, it contains a bug that can
+  cause a deadlock to occur if a connection drops unexpectedly (either due to
+  network issues or because the server closed the connection without warning)
+  when the server has already begun sending a response and Net::IMAP is
+  waiting to receive more data.
+
+  If this happens, Net::IMAP will continue waiting forever without passing
+  control back to Larch, and you will need to manually kill and restart Larch.
+
+* The Ruby package on Debian, Ubuntu, and some other Debian-based Linux
+  distributions doesn't include the OpenSSL standard library. If you see an
+  error like <tt>uninitialized constant Larch::IMAP::OpenSSL (NameError)</tt>
+  when running Larch, you may need to install the <tt>libopenssl-ruby</tt>
+  package. Please feel free to complain to the maintainer of your distribution's
+  Ruby packages.
+
+== Support
+
+The Larch mailing list is the best place for questions, comments, and discussion
+about Larch. You can join the list or view the archives at
+http://groups.google.com/group/larch
+
+== Credit
+
+The Larch::IMAP class borrows heavily from Sup[http://sup.rubyforge.org] by
+William Morgan, the source code of which should be required reading if you're
+doing anything with IMAP in Ruby.
+
+Larch uses the excellent Trollop[http://trollop.rubyforge.org] command-line
+option parser (also by William Morgan) and the
+HighLine[http://highline.rubyforge.org] command-line IO library (by James Edward
+Gray II).
+
+== License
+
+Copyright (c) 2009 Ryan Grove <ryan@wonko.com>
+
+Licensed under the GNU General Public License version 2.0.
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of version 2.0 of the GNU General Public License as published by the
+Free Software Foundation.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program; if not, visit http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+or write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+Boston, MA 02111-1307 USA.

data/bin/larch

@@ -22,18 +22,25 @@ EOS
     opt :from, "URI of the source IMAP server.", :short => '-f', :type => :string, :required => true
     opt :to,   "URI of the destination IMAP server.", :short => '-t', :type => :string, :required => true
 
-    text "\nOptions:"
+    text "\nCopy Options:"
+    opt :all,              "Copy all folders recursively", :short => :none
+    opt :all_subscribed,   "Copy all subscribed folders recursively", :short => :none
+    opt :exclude,          "List of mailbox names/patterns that shouldn't be copied", :short => :none, :type => :strings, :multi => true
+    opt :exclude_file,     "Filename containing mailbox names/patterns that shouldn't be copied", :short => :none, :type => :string
+    opt :from_folder,      "Source folder to copy from", :short => :none, :default => 'INBOX'
+    opt :from_pass,        "Source server password (default: prompt)", :short => :none, :type => :string
+    opt :from_user,        "Source server username (default: prompt)", :short => :none, :type => :string
+    opt :to_folder,        "Destination folder to copy to", :short => :none, :default => 'INBOX'
+    opt :to_pass,          "Destination server password (default: prompt)", :short => :none, :type => :string
+    opt :to_user,          "Destination server username (default: prompt)", :short => :none, :type => :string
 
-    # opt :dry_run,          "Don't actually do anything.", :short => '-n'
+    text "\nGeneral Options:"
+    opt :dry_run,          "Don't actually make any changes.", :short => '-n'
     opt :fast_scan,        "Use a faster (but less accurate) method to scan mailboxes. This may result in messages being re-copied.", :short => :none
-    opt :from_folder,      "Source folder to copy from", :short => :none, :default => 'INBOX'
-    opt :from_pass,        "Source server password (Default: prompt)", :short => :none, :type => :string
-    opt :from_user,        "Source server username (Default: prompt)", :short => :none, :type => :string
     opt :max_retries,      "Maximum number of times to retry after a recoverable error", :short => :none, :default => 3
     opt :no_create_folder, "Don't create destination folders that don't already exist", :short => :none
-    opt :to_folder,        "Destination folder to copy to", :short => :none, :default => 'INBOX'
-    opt :to_pass,          "Destination server password (Default: prompt)", :short => :none, :type => :string
-    opt :to_user,          "Destination server username (Default: prompt)", :short => :none, :type => :string
+    opt :ssl_certs,        "Path to a trusted certificate bundle to use to verify server SSL certificates", :short => :none, :type => :string
+    opt :ssl_verify,       "Verify server SSL certificates", :short => :none
     opt :verbosity,        "Output verbosity: debug, info, warn, error, or fatal", :short => '-V', :default => 'info'
   end
 
@@ -48,44 +55,94 @@ EOS
     Trollop.die :verbosity, "must be one of: #{Logger::LEVELS.keys.join(', ')}"
   end
 
-  # Create URIs.
-  options[:from]      = URI(options[:from])
-  options[:to]        = URI(options[:to])
-  options[:from].path = '/' + CGI.escape(options[:from_folder].gsub(/^\//, ''))
-  options[:to].path   = '/' + CGI.escape(options[:to_folder].gsub(/^\//, ''))
-
-  # Prompt for usernames and passwords if necessary.
-  unless options[:from_user]
-    options[:from_user] = ask("Source username (#{options[:from].host}): ")
+  if options[:exclude_file_given]
+    filename = options[:exclude_file]
+
+    Trollop.die :exclude_file, ": file not found: #{filename}" unless File.file?(filename)
+    Trollop.die :exclude_file, ": file cannot be read: #{filename}" unless File.readable?(filename)
   end
 
-  unless options[:from_pass]
-    options[:from_pass] = ask("Source password (#{options[:from].host}): ") {|q| q.echo = false }
+  # Prevent conflicting options from being used.
+  if options[:all_given]
+    [:all_subscribed, :from_folder, :to_folder].each do |o|
+      Trollop.die :all, "may not be used with --#{o.to_s.gsub('_', '-')}" if options["#{o}_given".to_sym]
+    end
   end
 
-  unless options[:to_user]
-    options[:to_user] = ask("Destination username (#{options[:to].host}): ")
+  if options[:all_subscribed_given]
+    [:all, :from_folder, :to_folder].each do |o|
+      Trollop.die :all_subscribed, "may not be used with --#{o.to_s.gsub('_', '-')}" if options["#{o}_given".to_sym]
+    end
   end
 
-  unless options[:to_pass]
-    options[:to_pass] = ask("Destination password (#{options[:to].host}): ") {|q| q.echo = false }
+  # Create URIs.
+  uri_from = URI(options[:from])
+  uri_to   = URI(options[:to])
+
+  # --all and --all-subscribed options override folders specified in URIs
+  if options[:all_given] || options[:all_subscribed_given]
+    uri_from.path = ''
+    uri_to.path   = ''
   end
 
+  # --from-folder and --to-folder options override folders specified in URIs
+  if options[:from_folder_given] || options[:to_folder_given]
+    uri_from.path = '/' + CGI.escape(options[:from_folder].gsub(/^\//, ''))
+    uri_to.path   = '/' + CGI.escape(options[:to_folder].gsub(/^\//, ''))
+  end
+
+  # Usernames and passwords specified as arguments override those in the URIs
+  uri_from.user     = CGI.escape(options[:from_user]) if options[:from_user]
+  uri_from.password = CGI.escape(options[:from_pass]) if options[:from_pass]
+  uri_to.user       = CGI.escape(options[:to_user]) if options[:to_user]
+  uri_to.password   = CGI.escape(options[:to_pass]) if options[:to_pass]
+
+  # If usernames/passwords aren't specified in either URIs or args, then prompt.
+  uri_from.user     ||= CGI.escape(ask("Source username (#{uri_from.host}): "))
+  uri_from.password ||= CGI.escape(ask("Source password (#{uri_from.host}): ") {|q| q.echo = false })
+  uri_to.user       ||= CGI.escape(ask("Destination username (#{uri_to.host}): "))
+  uri_to.password   ||= CGI.escape(ask("Destination password (#{uri_to.host}): ") {|q| q.echo = false })
+
   # Go go go!
-  init(options[:verbosity])
+  init(
+    options[:verbosity],
+    options[:exclude] ? options[:exclude].flatten : [],
+    options[:exclude_file]
+  )
 
-  source = IMAP.new(options[:from], options[:from_user], options[:from_pass],
-      :fast_scan   => options[:fast_scan],
-      :max_retries => options[:max_retries])
+  Net::IMAP.debug = true if @log.level == :insane
 
-  dest = IMAP.new(options[:to], options[:to_user], options[:to_pass],
-      :create_mailbox => !options[:no_create_folder],
+  imap_from = Larch::IMAP.new(uri_from,
+      :dry_run     => options[:dry_run],
+      :fast_scan   => options[:fast_scan],
+      :max_retries => options[:max_retries],
+      :ssl_certs   => options[:ssl_certs] || nil,
+      :ssl_verify  => options[:ssl_verify]
+  )
+
+  imap_to = Larch::IMAP.new(uri_to,
+      :create_mailbox => !options[:no_create_folder] && !options[:dry_run],
+      :dry_run        => options[:dry_run],
       :fast_scan      => options[:fast_scan],
-      :max_retries    => options[:max_retries])
-
-  for sig in [:SIGINT, :SIGQUIT, :SIGTERM]
-    trap(sig) { @log.fatal "Interrupted (#{sig})"; summary; exit }
+      :max_retries    => options[:max_retries],
+      :ssl_certs      => options[:ssl_certs] || nil,
+      :ssl_verify     => options[:ssl_verify]
+  )
+
+  unless RUBY_PLATFORM =~ /mswin|mingw|bccwin|wince|java/
+    begin
+      for sig in [:SIGINT, :SIGQUIT, :SIGTERM]
+        trap(sig) { @log.fatal "Interrupted (#{sig})"; Kernel.exit }
+      end
+    rescue => e
+    end
   end
 
-  copy(source, dest)
+  if options[:all_given]
+    copy_all(imap_from, imap_to)
+  elsif options[:all_subscribed_given]
+    copy_all(imap_from, imap_to, true)
+  else
+    copy_folder(imap_from, imap_to)
+  end
 end

data/lib/larch/errors.rb

@@ -4,6 +4,7 @@ module Larch
   class IMAP
     class Error < Larch::Error; end
     class FatalError < Error; end
-    class NotFoundError < Error; end
+    class MailboxNotFoundError < Error; end
+    class MessageNotFoundError < Error; end
   end
 end

data/lib/larch/imap/mailbox.rb

@@ -0,0 +1,279 @@
+module Larch; class IMAP
+
+# Represents an IMAP mailbox.
+class Mailbox
+  attr_reader :attr, :delim, :imap, :name, :state
+
+  # Regex to capture a Message-Id header.
+  REGEX_MESSAGE_ID = /message-id\s*:\s*(\S+)/i
+
+  # Minimum time (in seconds) allowed between mailbox scans.
+  SCAN_INTERVAL = 60
+
+  def initialize(imap, name, delim, subscribed, *attr)
+    raise ArgumentError, "must provide a Larch::IMAP instance" unless imap.is_a?(Larch::IMAP)
+
+    @imap       = imap
+    @name       = name
+    @delim      = delim
+    @subscribed = subscribed
+    @attr       = attr.flatten
+
+    @ids       = {}
+    @last_id   = 0
+    @last_scan = nil
+    @mutex     = Mutex.new
+
+    # Valid mailbox states are :closed (no mailbox open), :examined (mailbox
+    # open and read-only), or :selected (mailbox open and read-write).
+    @state = :closed
+
+    # Create private convenience methods (debug, info, warn, etc.) to make
+    # logging easier.
+    Logger::LEVELS.each_key do |level|
+      Mailbox.class_eval do
+        define_method(level) do |msg|
+          Larch.log.log(level, "#{@imap.username}@#{@imap.host}: #{@name}: #{msg}")
+        end
+
+        private level
+      end
+    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?(Larch::IMAP::Message)
+    return false if has_message?(message)
+
+    @imap.safely do
+      unless imap_select(!!@imap.options[:create_mailbox])
+        raise Larch::IMAP::Error, "mailbox cannot contain messages: #{@name}"
+      end
+
+      debug "appending message: #{message.id}"
+      @imap.conn.append(@name, message.rfc822, message.flags, message.internaldate) unless @imap.options[:dry_run]
+    end
+
+    true
+  end
+  alias << append
+
+  # Iterates through Larch message ids in this mailbox, yielding each one to the
+  # provided block.
+  def each
+    scan
+    @ids.dup.each_key {|id| yield id }
+  end
+
+  # Gets a Net::IMAP::Envelope for the specified message id.
+  def envelope(message_id)
+    scan
+    raise Larch::IMAP::MessageNotFoundError, "message not found: #{message_id}" unless uid = @ids[message_id]
+
+    debug "fetching envelope: #{message_id}"
+    imap_uid_fetch([uid], 'ENVELOPE').first.attr['ENVELOPE']
+  end
+
+  # Fetches a Larch::IMAP::Message struct representing the message with the
+  # specified Larch message id.
+  def fetch(message_id, peek = false)
+    scan
+    raise Larch::IMAP::MessageNotFoundError, "message not found: #{message_id}" unless uid = @ids[message_id]
+
+    debug "#{peek ? 'peeking at' : 'fetching'} message: #{message_id}"
+    data = imap_uid_fetch([uid], [(peek ? 'BODY.PEEK[]' : 'BODY[]'), 'FLAGS', 'INTERNALDATE', 'ENVELOPE']).first
+
+    Message.new(message_id, data.attr['ENVELOPE'], data.attr['BODY[]'],
+        data.attr['FLAGS'], Time.parse(data.attr['INTERNALDATE']))
+  end
+  alias [] fetch
+
+  # 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
+    @ids.has_key?(message_id)
+  end
+
+  # Gets the number of messages in this mailbox.
+  def length
+    scan
+    @ids.length
+  end
+  alias size length
+
+  # Same as fetch, but doesn't mark the message as seen.
+  def peek(message_id)
+    fetch(message_id, true)
+  end
+
+  # Resets the mailbox state.
+  def reset
+    @mutex.synchronize { @state = :closed }
+  end
+
+  # Fetches message headers from this mailbox.
+  def scan
+    return if @last_scan && (Time.now - @last_scan) < SCAN_INTERVAL
+
+    begin
+      return unless imap_examine
+    rescue Error => e
+      return if @imap.options[:create_mailbox]
+      raise
+    end
+
+    last_id = @imap.safely { @imap.conn.responses['EXISTS'].last }
+    @mutex.synchronize { @last_scan = Time.now }
+    return if last_id == @last_id
+
+    range = (@last_id + 1)..last_id
+    @mutex.synchronize { @last_id = last_id }
+
+    info "fetching message headers #{range}" <<
+        (@imap.options[:fast_scan] ? ' (fast scan)' : '')
+
+    fields = if @imap.options[:fast_scan]
+      ['UID', 'RFC822.SIZE', 'INTERNALDATE']
+    else
+      "(UID BODY.PEEK[HEADER.FIELDS (MESSAGE-ID)] RFC822.SIZE INTERNALDATE)"
+    end
+
+    imap_fetch(range.begin..-1, fields).each do |data|
+      id = create_id(data)
+
+      unless uid = data.attr['UID']
+        error "UID not in IMAP response for message: #{id}"
+        next
+      end
+
+      if Larch.log.level == :debug && @ids.has_key?(id)
+        envelope = imap_uid_fetch([uid], 'ENVELOPE').first.attr['ENVELOPE']
+        debug "duplicate message? #{id} (Subject: #{envelope.subject})"
+      end
+
+      @mutex.synchronize { @ids[id] = uid }
+    end
+  end
+
+  # Subscribes to this mailbox.
+  def subscribe(force = false)
+    return if subscribed? && !force
+    @imap.safely { @imap.conn.subscribe(@name) } unless @imap.options[:dry_run]
+    @mutex.synchronize { @subscribed = true }
+  end
+
+  # Returns +true+ if this mailbox is subscribed, +false+ otherwise.
+  def subscribed?
+    @subscribed
+  end
+
+  # Unsubscribes from this mailbox.
+  def unsubscribe(force = false)
+    return unless subscribed? || force
+    @imap.safely { @imap.conn.unsubscribe(@name) } unless @imap.options[:dry_run]
+    @mutex.synchronize { @subscribed = false }
+  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 Error, "required 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
+  end
+
+  # Examines the mailbox. If _force_ is true, the mailbox will be examined even
+  # if it is already selected (which isn't necessary unless you want to ensure
+  # that it's in a read-only state).
+  def imap_examine(force = false)
+    return false if @attr.include?(:Noselect)
+    return true if @state == :examined || (!force && @state == :selected)
+
+    @imap.safely do
+      begin
+        @mutex.synchronize { @state = :closed }
+
+        debug "examining mailbox"
+        @imap.conn.examine(@name)
+
+        @mutex.synchronize { @state = :examined }
+
+      rescue Net::IMAP::NoResponseError => e
+        raise Error, "unable to examine mailbox: #{e.message}"
+      end
+    end
+
+    return true
+  end
+
+  # Fetches the specified _fields_ for the specified _set_ of message sequence
+  # ids (either a Range or an Array of ids).
+  def imap_fetch(set, fields)
+    @imap.safely do
+      imap_examine
+      @imap.conn.fetch(set, fields)
+    end
+  end
+
+  # Selects the mailbox if it is not already selected. If the mailbox does not
+  # exist and _create_ is +true+, it will be created. Otherwise, a
+  # Larch::IMAP::Error will be raised.
+  def imap_select(create = false)
+    return false if @attr.include?(:Noselect)
+    return true if @state == :selected
+
+    @imap.safely do
+      begin
+        @mutex.synchronize { @state = :closed }
+
+        debug "selecting mailbox"
+        @imap.conn.select(@name)
+
+        @mutex.synchronize { @state = :selected }
+
+      rescue Net::IMAP::NoResponseError => e
+        raise Error, "unable to select mailbox: #{e.message}" unless create
+
+        info "creating mailbox: #{@name}"
+
+        begin
+          @imap.conn.create(@name) unless @imap.options[:dry_run]
+          retry
+        rescue => e
+          raise Error, "unable to create mailbox: #{e.message}"
+        end
+      end
+    end
+
+    return true
+  end
+
+  # Fetches the specified _fields_ for the specified _set_ of UIDs (either a
+  # Range or an Array of UIDs).
+  def imap_uid_fetch(set, fields)
+    @imap.safely do
+      imap_examine
+      @imap.conn.uid_fetch(set, fields)
+    end
+  end
+
+end
+
+end; end