em-imap 0.1.1 → 0.2

data/README.md

@@ -10,7 +10,7 @@ This document tries to introduce concepts of IMAP alongside the facilities of th
 
 ### Connecting
 
-Before you can communicate with an IMAP server, you must first connect to it. There are three connection parameters, the hostname, the port number, and whether to use SSL/TLS. As with every method in EM::IMAP, `EM::IMAP.connect` returns a [deferrable](http://eventmachine.rubyforge.org/docs/DEFERRABLES.html) enhanced by the [deferrable\_gratification](https://github.com/samstokes/deferrable_gratification) library.
+Before you can communicate with an IMAP server, you must first connect to it. There are three connection parameters, the hostname, the port number, and whether to use SSL/TLS. As with every method in EM::IMAP, `EM::IMAP::Client#connect` returns a [deferrable](http://eventmachine.rubyforge.org/docs/DEFERRABLES.html) enhanced by the [deferrable\_gratification](https://github.com/samstokes/deferrable_gratification) library.
 
 For example, to connect to Gmail's IMAP server, you can use the following snippet:
 
@@ -18,8 +18,8 @@ For example, to connect to Gmail's IMAP server, you can use the following snippe
     require 'em-imap'
 
     EM::run do
-      client = EM::IMAP.connect('imap.gmail.com', 993, true)
-      client.errback do |error|
+      client = EM::IMAP.new('imap.gmail.com', 993, true)
+      client.connect.errback do |error|
         puts "Connecting failed: #{error}"
       end.callback do |hello_response|
         puts "Connecting succeeded!"
@@ -34,8 +34,8 @@ There are two authentication mechanisms in IMAP, `LOGIN` and `AUTHENTICATE`, exp
 
 Extending our previous example to also log in to Gmail:
 
-    client = EM::IMAP.connect('imap.gmail.com', 993, true)
-    client.bind! do
+    client = EM::IMAP.new('imap.gmail.com', 993, true)
+    client.connect.bind! do
       client.login("conrad.irwin@gmail.com", ENV["GMAIL_PASSWORD"])
     end.callback do
       puts "Connected and logged in!"
@@ -49,8 +49,8 @@ The `.authenticate` method is more advanced and uses the same extensible mechani
 
 Once the authentication has completed successfully, you can perform IMAP commands that don't require a currently selected mailbox. For example to get a list of the names of all Gmail mailboxes (including labels):
 
-    client = EM::IMAP.connect('imap.gmail.com', 993, true)
-    client.bind! do
+    client = EM::IMAP.new('imap.gmail.com', 993, true)
+    client.connect.bind! do
       client.login("conrad.irwin@gmail.com", ENV["GMAIL_PASSWORD"])
     end.bind! do
       client.list
@@ -68,8 +68,8 @@ In order to do useful things which actual messages, you need to first select a m
 
 For example to search for all emails relevant to em-imap in Gmail:
 
-    client = EM::IMAP.connect('imap.gmail.com', 993, true)
-    client.bind! do
+    client = EM::IMAP.new('imap.gmail.com', 993, true)
+    client.connect.bind! do
       client.login("conrad.irwin@gmail.com", ENV["GMAIL_PASSWORD"])
     end.bind! do
       client.select('[Google Mail]/All Mail')
@@ -83,8 +83,8 @@ For example to search for all emails relevant to em-imap in Gmail:
 
 Once you have a list of message sequence numbers, as returned by search, you can actually read the emails with `.fetch`:
 
-    client = EM::IMAP.connect('imap.gmail.com', 993, true)
-    client.bind! do
+    client = EM::IMAP.new('imap.gmail.com', 993, true)
+    client.connect.bind! do
       client.login("conrad.irwin@gmail.com", ENV["GMAIL_PASSWORD"])
     end.bind! do
       client.select('[Google Mail]/All Mail')
@@ -148,7 +148,8 @@ If you want to receive server responses at any time, you can call `.add_response
 
 If you want to send commands without waiting for previous replies, you can also do so. em-imap handles the few cases where this is not permitted (for example, during an IDLE command) by queueing the command until the connection becomes available again. If you do this, bear in mind that any blocks that are listening on the connection may receive responses from multiple commands interleaved.
 
-    client = EM::Imap.connect('imap.gmail.com', 993, true).callback do
+    client = EM::Imap.new('imap.gmail.com', 993, true)
+    client.connect.callback do
       logger_in = client.login('conrad.irwin@gmail.com', ENV["GMAIL_PASSWORD"])
       selecter = client.select('[Google Mail]/All Mail')
       searcher = client.search('from:conrad@rapportive.com').callback do |results|
@@ -172,6 +173,10 @@ Before version 1, at least the following changes should be made:
 4. Support SORT and THREAD.
 5. Put the in-line documentation into a real format.
 
+### Breaking Changes
+
+Between Version 0.1(.x) and 0.2, the connection setup API changed. Previously you would call `EM::IMAP.connect`, now that is broken into two steps: `EM::IMAP.new` and `EM::IMAP::Client#connect` as documented above. This makes it less likely people will write `client = connect.bind!` by accident, and allows you to bind to the `errback` of the connection as a whole should you wish to.
+
 ## Meta-foo
 
 Em-imap is made available under the MIT license, see LICENSE.MIT for details

data/lib/em-imap/client.rb

@@ -7,8 +7,16 @@ module EventMachine
 
       include IMAP::Authenticators
 
-      def initialize(connection)
-        @connection = connection.errback{ |e| fail e }.callback{ |response| succeed response }
+      def initialize(host, port, usessl=false)
+        @connect_args=[host, port, usessl]
+      end
+
+      def connect
+        @connection = EM::IMAP::Connection.connect(*@connect_args)
+        @connection.errback{ |e| fail e }.
+                    callback{ |*args| succeed *args }
+
+        @connection.hello_listener
       end
 
       def disconnect

data/lib/em-imap/command_sender.rb

@@ -1,44 +1,96 @@
 module EventMachine
   module IMAP
-    # Provides a send_command_object method that serializes command objects
-    # and uses send_data on them. This is the ugly sister to ResponseParser.
+    # Used to send commands, and various other pieces of data, to the IMAP
+    # server as they are needed. Plugs in the ContinuationSynchronisation module
+    # so that the outgoing channel is free of racey-behaviour.
     module CommandSender
-      # Ugly hack to get at the Net::IMAP string formatting routines.
-      # (FIXME: Extract into its own module and rewrite)
-      class FakeNetIMAP < Net::IMAP
-        def initialize(command, imap_connection)
-          @command = command
-          @connection = imap_connection
-        end
-
-        def put_string(str)
-          @connection.send_string str, @command
+      # Send a command to the IMAP server.
+      #
+      # @param command, The command to send.
+      #
+      # This method has two phases, the first of which is to convert your
+      # command into tokens for sending over the network, and the second is to
+      # actually send those fragments.
+      #
+      # If the conversion fails, a Net::IMAP::DataFormatError will be raised
+      # which you should handle synchronously. If the sending fails, then the
+      # command will be failed asynchronously.
+      #
+      def send_command_object(command)
+        Formatter.format(command) do |to_send|
+          if to_send.is_a? Formatter::Literal
+            send_literal to_send.str, command
+          else
+            send_string  to_send, command
+          end
         end
+      end
 
-        def send_literal(str)
-          @connection.send_literal str, @command
+      # Send some normal (binary/string) data to the server.
+      #
+      # @param str, the data to send
+      # @param command, the command for which the data is being sent.
+      #
+      # This uses the LineBuffer, and fails the command if the network
+      # connection has died for some reason.
+      #
+      def send_string(str, command)
+        when_not_awaiting_continuation do
+          begin
+            send_line_buffered str
+          rescue => e
+            command.fail e
+          end
         end
-
-        public :send_data
       end
 
-      # This is a method that synchronously converts the command into fragments
-      # of string.
+      # Send an IMAP literal to the server.
       #
-      # If you pass something that cannot be serialized, an exception will be raised.
-      # If however, something fails at the socket level, the command will be failed.
-      def send_command_object(command)
-        sender = FakeNetIMAP.new(command, self)
-
-        sender.put_string "#{command.tag} #{command.cmd}"
-        command.args.each do |arg|
-          sender.put_string " "
-          sender.send_data arg
+      # @param literal, the string to send.
+      # @param command, the command associated with this string.
+      #
+      # Sending literals is a somewhat complicated process:
+      #
+      # Step 1. Client tells the server how big the literal will be.
+      #   (and at the same time shows the server the contents of the command so
+      #   far)
+      # Step 2. The server either accepts (with a ContinuationResponse) or
+      #   rejects (with a BadResponse) the continuation based on the size of the
+      #   literal, and the validity of the line so far.
+      # Step 3. The client sends the literal, followed by a linefeed, and then
+      # continues with sending the rest of the command.
+      #
+      def send_literal(literal, command)
+        when_not_awaiting_continuation do
+          begin
+            send_line_buffered "{" + literal.size.to_s + "}" + CRLF
+          rescue => e
+            command.fail e
+          end
+          waiter = await_continuations do
+            begin
+              send_data literal
+            rescue => e
+              command.fail e
+            end
+            waiter.stop
+          end
+          command.errback{ waiter.stop }
         end
-        sender.put_string CRLF
       end
 
-      # See Net::IMAP#authenticate
+      # Pass a challenge/response between the server and the auth_handler.
+      #
+      # @param auth_handler, an authorization handler.
+      # @param command, the associated AUTHORIZE command.
+      #
+      # This can be called several times in one authorization handshake
+      # depending on how many messages the server wishes to see from the
+      # auth_handler.
+      #
+      # If the auth_handler raises an exception, or the network connection dies
+      # for some reason, the command will be failed.
+      #
       def send_authentication_data(auth_handler, command)
         when_not_awaiting_continuation do
           waiter = await_continuations do |response|
@@ -54,6 +106,14 @@ module EventMachine
         end
       end
 
+      # Register a stopback on the IDLE command that sends the DONE
+      # continuation that the server is waiting for.
+      #
+      # @param command, The IDLE command.
+      #
+      # This blocks the outgoing connection until the IDLE command is stopped,
+      # as required by RFC 2177.
+      #
       def prepare_idle_continuation(command)
         when_not_awaiting_continuation do
           waiter = await_continuations
@@ -68,35 +128,12 @@ module EventMachine
         end
       end
 
-      def send_string(str, command)
-        when_not_awaiting_continuation do
-          begin
-            send_line_buffered str
-          rescue => e
-            command.fail e
-          end
-        end
-      end
-
-      def send_literal(literal, command)
-        when_not_awaiting_continuation do
-          begin
-            send_line_buffered "{" + literal.size.to_s + "}" + CRLF
-          rescue => e
-            command.fail e
-          end
-          waiter = await_continuations do
-            begin
-              send_data literal
-            rescue => e
-              command.fail e
-            end
-            waiter.stop
-          end
-          command.errback{ waiter.stop }
-        end
-      end
 
+      # Buffers out-going string sending by-line.
+      #
+      # This is safe to do for IMAP because the client always ends transmission
+      # on a CRLF (for awaiting continuation requests, and for ending commands)
+      #
       module LineBuffer
         def post_init
           super

data/lib/em-imap/connection.rb

@@ -25,6 +25,38 @@ module EventMachine
         end
       end
 
+      def post_init
+        @listeners = []
+        super
+        listen_for_failure
+        listen_for_greeting
+      end
+
+      # This listens for the IMAP connection to have been set up. This should
+      # be shortly after the TCP connection is available, once we've received
+      # a greeting from the server.
+      def listen_for_greeting
+        add_to_listener_pool(hello_listener)
+        hello_listener.listen do |response|
+          # TODO: Is this the right condition? I think it can be one of several
+          # possible answers depending on how trusted the connection is, but probably
+          # not *anything* except BYE.
+          if response.is_a?(Net::IMAP::UntaggedResponse) && response.name != "BYE"
+            hello_listener.succeed response
+          else
+            hello_listener.fail Net::IMAP::ResponseParseError.new(response.raw_data)
+          end
+        end.errback do |e|
+          hello_listener.fail e
+        end
+      end
+
+      # Returns a Listener that is active during connection setup, and which is succeeded
+      # or failed as soon as we've received a greeting from the server.
+      def hello_listener
+        @hello_listener ||= Listener.new.errback{ |e| fail e }.bothback{ hello_listener.stop }
+      end
+
       # Send the command, with the given arguments, to the IMAP server.
       #
       # @param cmd, the name of the command to send (a string)
@@ -48,7 +80,6 @@ module EventMachine
         Command.new(next_tag!, cmd, args).tap do |command|
           add_to_listener_pool(command)
           listen_for_tagged_response(command)
-          listen_for_bye_response(command)
           send_command_object(command)
         end
       end
@@ -67,49 +98,9 @@ module EventMachine
         Listener.new(&block).tap do |listener|
           listener.stopback{ listener.succeed }
           add_to_listener_pool(listener)
-          listen_for_bye_response(listener)
-        end
-      end
-
-      def post_init
-        @listeners = Set.new
-        super
-        listen_for_greeting
-      end
-
-      # Listen for the first response from the server and succeed or fail
-      # the connection deferrable.
-      def listen_for_greeting
-        hello_listener = add_response_handler do |response|
-          hello_listener.stop
-          if response.is_a?(Net::IMAP::UntaggedResponse)
-            if response.name == "BYE"
-              fail Net::IMAP::ByeResponseError.new(response.raw_data)
-            else
-              succeed response
-            end
-          else
-            fail Net::IMAP::ResponseParseError.new(response.raw_data)
-          end
-        end.errback do |e|
-          fail e
         end
       end
 
-      # Called when the connection is closed.
-      # TODO: Figure out how to send a useful error...
-      def unbind
-        fail_all EOFError.new("Connection to IMAP server was unbound"), true
-      end
-
-      def fail_all(error, closed=false)
-        # NOTE: Take a shallow clone of the listeners here so that we get guaranteed
-        # behaviour. We want to fail any listeners that may be added by the errbacks
-        # of other listeners.
-        @listeners.clone.each{ |listener| listener.fail error } while @listeners.size > 0
-        close_connection unless closed
-      end
-
       def add_to_listener_pool(listener)
         @listeners << listener.bothback{ @listeners.delete listener }
       end
@@ -140,12 +131,31 @@ module EventMachine
         end
       end
 
-      # If we receive a BYE response from the server, then we're not going
-      # to hear any more, so we fail all our listeners.
-      def listen_for_bye_response(listener)
-        listener.listen do |response|
+      # Called when the connection is closed.
+      # TODO: Figure out how to send a useful error...
+      def unbind
+        @unbound = true
+        fail EOFError.new("Connection to IMAP server was unbound")
+      end
+
+      # Attach life-long listeners on various conditions that we want to treat as connection
+      # errors. When such an error occurs, we want to fail all the currently pending commands
+      # so that the user of the library doesn't have to subscribe to more than one stream
+      # of errors.
+      def listen_for_failure
+        errback do |error|
+          # NOTE: Take a shallow clone of the listeners here so that we get guaranteed
+          # behaviour. We want to fail any listeners that may be added by the errbacks
+          # of other listeners.
+          @listeners.clone.each{ |listener| listener.fail error } while @listeners.size > 0
+          close_connection unless @unbound
+        end
+
+        # If we receive a BYE response from the server, then we're not going
+        # to hear any more, so we fail all our listeners.
+        add_response_handler do |response|
           if response.is_a?(Net::IMAP::UntaggedResponse) && response.name == "BYE"
-            listener.fail Net::IMAP::ByeResponseError.new(response.raw_data)
+            fail Net::IMAP::ByeResponseError.new(response.raw_data)
           end
         end
       end

data/lib/em-imap/continuation_synchronisation.rb

@@ -63,7 +63,7 @@ module EventMachine
             if awaiting_continuation?
               @awaiting_continuation.receive_event response
             else
-              fail_all Net::IMAP::ResponseError.new("Unexpected continuation response from server")
+              fail Net::IMAP::ResponseError.new("Unexpected continuation response from server")
             end
           end
         end

data/lib/em-imap/formatter.rb

@@ -0,0 +1,124 @@
+module EventMachine
+  module IMAP
+    class Formatter
+
+      # A placeholder so that the command sender knows to treat literal strings specially
+      class Literal < Struct.new(:str); end
+
+      # Format the data to be sent into strings and literals, and call the block
+      # for each token to be sent.
+      #
+      # @param data   The data to format,
+      # @param &block The callback, which will be called with a number of strings and
+      #               EM::IMAP::Formatter::Literal instances.
+      #
+      # NOTE: The block is responsible for handling any network-level concerns, such
+      # as sending literals only with permission.
+      #
+      def self.format(data, &block)
+        new(&block).send_data(data)
+      end
+
+      def initialize(&block)
+        @block = block
+      end
+
+      def put_string(str)
+        @block.call str
+      end
+
+      def send_literal(str)
+        @block.call Literal.new(str)
+      end
+
+      # The remainder of the code in this file is directly from Net::IMAP.
+      # Copyright (C) 2000  Shugo Maeda <shugo@ruby-lang.org>
+      def send_data(data)
+        case data
+        when nil
+          put_string("NIL")
+        when String
+          send_string_data(data)
+        when Integer
+          send_number_data(data)
+        when Array
+          send_list_data(data)
+        when Time
+          send_time_data(data)
+        when Symbol
+          send_symbol_data(data)
+        when EM::IMAP::Command
+          send_command(data)
+        else
+          data.send_data(self)
+        end
+      end
+
+      def send_command(cmd)
+        put_string cmd.tag
+        put_string " "
+        put_string cmd.cmd
+        cmd.args.each do |i|
+          put_string " "
+          send_data(i)
+        end
+        put_string "\r\n"
+      end
+
+      def send_string_data(str)
+        case str
+        when ""
+          put_string('""')
+        when /[\x80-\xff\r\n]/n
+          # literal
+          send_literal(str)
+        when /[(){ \x00-\x1f\x7f%*"\\]/n
+          # quoted string
+          send_quoted_string(str)
+        else
+          put_string(str)
+        end
+      end
+
+      def send_quoted_string(str)
+        put_string('"' + str.gsub(/["\\]/n, "\\\\\\&") + '"')
+      end
+
+      def send_number_data(num)
+        if num < 0 || num >= 4294967296
+          raise Net::IMAP::DataFormatError, num.to_s
+        end
+        put_string(num.to_s)
+      end
+
+      def send_list_data(list)
+        put_string("(")
+        first = true
+        list.each do |i|
+          if first
+            first = false
+          else
+            put_string(" ")
+          end
+          send_data(i)
+        end
+        put_string(")")
+      end
+
+      DATE_MONTH = %w(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
+
+      def send_time_data(time)
+        t = time.dup.gmtime
+        s = format('"%2d-%3s-%4d %02d:%02d:%02d +0000"',
+                   t.day, DATE_MONTH[t.month - 1], t.year,
+                   t.hour, t.min, t.sec)
+        put_string(s)
+      end
+
+      def send_symbol_data(symbol)
+        put_string("\\" + symbol.to_s)
+      end
+
+    end
+  end
+end

data/lib/em-imap/listener.rb

@@ -92,7 +92,6 @@ module EventMachine
       # Register a block to be called when receive_event is called.
       def listen(&block)
         listeners << block
-        stopback{ |*args| listeners.delete block }
         self
       end
 

data/lib/em-imap/response_parser.rb

@@ -39,15 +39,12 @@ module EventMachine
       # Callback used by receive data.
       def receive_response(response); end
 
-      # Callback used if something goes wrong.
-      def fail_all(error); end
-
       private
 
       def parse(line)
         @parser.parse(line)
       rescue Net::IMAP::ResponseParseError => e
-        fail_all e
+        fail e
       end
     end
   end

data/lib/em-imap.rb

@@ -8,6 +8,7 @@ require 'deferrable_gratification'
 $:.unshift File.dirname( __FILE__ )
 require 'em-imap/listener'
 require 'em-imap/continuation_synchronisation'
+require 'em-imap/formatter'
 require 'em-imap/command_sender'
 require 'em-imap/response_parser'
 require 'em-imap/connection'
@@ -27,6 +28,10 @@ module EventMachine
       Client.new(EventMachine::IMAP::Connection.connect(host, port, ssl))
     end
 
+    def self.new(host, port, ssl=false)
+      Client.new(host, port, ssl)
+    end
+
     class Command < Listener
       attr_accessor :tag, :cmd, :args
       def initialize(tag, cmd, args=[], &block)

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: em-imap
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 15
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: "0.2"
 platform: ruby
 authors: 
 - Conrad Irwin
@@ -72,6 +71,7 @@ extra_rdoc_files: []
 files: 
 - lib/em-imap.rb
 - lib/em-imap/listener.rb
+- lib/em-imap/formatter.rb
 - lib/em-imap/command_sender.rb
 - lib/em-imap/authenticators.rb
 - lib/em-imap/connection.rb