em-imap 0.1

data/lib/em-imap/command_sender.rb

@@ -0,0 +1,118 @@
+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.
+    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
+        end
+
+        def send_literal(str)
+          @connection.send_literal str, @command
+        end
+
+        public :send_data
+      end
+
+      # This is a method that synchronously converts the command into fragments
+      # of string.
+      #
+      # 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
+        end
+        sender.put_string CRLF
+      end
+
+      # See Net::IMAP#authenticate
+      def send_authentication_data(auth_handler, command)
+        when_not_awaiting_continuation do
+          waiter = await_continuations do |response|
+            begin
+              data = auth_handler.process(response.data.text.unpack("m")[0])
+              s = [data].pack("m").gsub(/\n/, "")
+              send_data(s + CRLF)
+            rescue => e
+              command.fail e
+            end
+          end
+          command.bothback{ |*args| waiter.stop }
+        end
+      end
+
+      def prepare_idle_continuation(command)
+        when_not_awaiting_continuation do
+          waiter = await_continuations
+          command.stopback do
+            waiter.stop
+            begin
+              send_data "DONE\r\n"
+            rescue => e
+              command.fail e
+            end
+          end
+        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
+
+      module LineBuffer
+        def post_init
+          super
+          @line_buffer = ""
+        end
+
+        def send_line_buffered(str)
+          @line_buffer += str
+          while eol = @line_buffer.index(CRLF)
+            to_send = @line_buffer.slice! 0, eol + CRLF.size
+            send_data to_send
+          end
+        end
+      end
+      include IMAP::CommandSender::LineBuffer
+      include IMAP::ContinuationSynchronisation
+    end
+  end
+end

data/lib/em-imap/connection.rb

@@ -0,0 +1,181 @@
+module EventMachine
+  module IMAP
+    CRLF = "\r\n"
+    module Connection
+      include EM::Deferrable
+      DG.enhance!(self)
+
+      include IMAP::CommandSender
+      include IMAP::ResponseParser
+
+      # Create a new connection to an IMAP server.
+      #
+      # @param host, The host name (warning DNS lookups are synchronous)
+      # @param port, The port to connect to.
+      # @param ssl=false, Whether or not to use TLS.
+      #
+      # @return Connection, a deferrable that will succeed when the server
+      #                     has replied with OK or PREAUTH, or fail if the
+      #                     connection could not be established, or the
+      #                     first response was BYE.
+      #
+      def self.connect(host, port, ssl=false)
+        conn = EventMachine.connect(host, port, self).tap do |conn|
+          conn.start_tls if ssl
+        end
+      end
+
+      # Send the command, with the given arguments, to the IMAP server.
+      #
+      # @param cmd, the name of the command to send (a string)
+      # @param *args, the arguments for the command, serialized
+      #               by Net::IMAP. (FIXME)
+      #
+      # @return Command, a listener and deferrable that will receive_event
+      #                  with the responses from the IMAP server, and which
+      #                  will succeed with a tagged response from the
+      #                  server, or fail with a tagged error response, or
+      #                  an exception.
+      #
+      #                  NOTE: The responses it overhears may be intended
+      #                  for other commands that are running in parallel.
+      #
+      # Exceptions thrown during serialization will be thrown to the user,
+      # exceptions thrown while communicating to the socket will cause the
+      # returned command to fail.
+      #
+      def send_command(cmd, *args)
+        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
+
+      # Create a new listener for responses from the IMAP server.
+      #
+      # @param  &block, a block to which all responses will be passed.
+      # @return Listener, an object with a .stop method that you can
+      #         use to unregister this block.
+      #
+      #         You may also want to listen on the Listener's errback
+      #         for when problems arise. The Listener's callbacks will
+      #         be called after you call its stop method.
+      #
+      def add_response_handler(&block)
+        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.
+      # If there are any listeners left, we fail them.
+      # (TODO: Should we actually succeed them if the connection was
+      # explicitly closed by us?)
+      # TODO: Figure out how to send a useful error...
+      def unbind
+        @listeners.each{ |listener| listener.fail EOFError.new("Connection to IMAP server was unbound") }
+      end
+
+      def add_to_listener_pool(listener)
+        @listeners << listener.bothback{ @listeners.delete listener }
+      end
+
+      # receive_response is a higher-level receive_data provided by
+      # EM::IMAP::ResponseParser. Each response is a Net::IMAP response
+      # object. (FIXME)
+      def receive_response(response)
+        @listeners.each{ |listener| listener.receive_event response }
+      end
+
+      # Await the response that marks the completion of this command,
+      # and succeed or fail the command as appropriate.
+      def listen_for_tagged_response(command)
+        command.listen do |response|
+          if response.is_a?(Net::IMAP::TaggedResponse) && response.tag == command.tag
+            case response.name
+            when "NO"
+              command.fail Net::IMAP::NoResponseError.new(response.data.text)
+            when "BAD"
+              command.fail Net::IMAP::BadResponseError.new(response.data.text)
+            else
+              command.succeed response
+            end
+          end
+        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|
+          if response.is_a?(Net::IMAP::UntaggedResponse) && response.name == "BYE"
+            listener.fail Net::IMAP::ByeResponseError.new(response.raw_data)
+          end
+        end
+      end
+
+      # Provides a next_tag! method to generate unique tags
+      # for an IMAP session.
+      module TagSequence
+        def post_init
+          super
+          # Copying Net::IMAP
+          @tag_prefix = "RUBY"
+          @tagno = 0
+        end
+
+        def next_tag!
+          @tagno += 1
+          "%s%04d" % [@tag_prefix, @tagno]
+        end
+      end
+
+      # Intercepts send_data and receive_data and logs them to STDOUT,
+      # this should be the last module included.
+      module Debug
+        def send_data(data)
+          puts "C: #{data.inspect}"
+          super
+        end
+
+        def receive_data(data)
+          puts "S: #{data.inspect}"
+          super
+        end
+      end
+      include IMAP::Connection::TagSequence
+      def self.debug!
+        include IMAP::Connection::Debug
+      end
+    end
+  end
+end

data/lib/em-imap/continuation_synchronisation.rb

@@ -0,0 +1,85 @@
+module EventMachine
+  module IMAP
+    # The basic IMAP protocol is an unsynchronised exchange of lines,
+    # however under some circumstances it is necessary to synchronise
+    # so that the server acknowledges each item sent by the client.
+    #
+    # For example, this happens during authentication:
+    #
+    #  C: A0001 AUTHENTICATE LOGIN
+    #  S: + 
+    #  C: USERNAME
+    #  S: +
+    #  C: PASSWORD
+    #  S: A0001 OK authenticated as USERNAME.
+    #
+    # And during the sending of literals:
+    #
+    #  C: A0002 SELECT {8}
+    #  S: + continue
+    #  C: All Mail
+    #  S: A0002 OK
+    #
+    # In order to make this work this module allows part of the client
+    # to block the outbound link while waiting for the continuation
+    # responses that it is expecting.
+    #
+    module ContinuationSynchronisation
+
+      def post_init
+        super
+        @awaiting_continuation = nil
+        listen_for_continuation
+      end
+
+      def awaiting_continuation?
+        !!@awaiting_continuation
+      end
+
+      # Await further continuation responses from the server, and
+      # pass them to the given block.
+      #
+      # As a side-effect causes when_not_awaiting_continuations to
+      # queue further blocks instead of executing them immediately.
+      #
+      # NOTE: If there's currently a different block awaiting continuation
+      # responses, this block will be added to its queue.
+      def await_continuations(&block)
+        Listener.new(&block).tap do |waiter|
+          when_not_awaiting_continuation do
+            @awaiting_continuation = waiter.stopback do
+              @awaiting_continuation = nil
+              waiter.succeed
+            end
+          end
+        end
+      end
+
+      # Add a single, permanent listener to the connection that forwards
+      # continuation responses onto the currently awaiting block.
+      def listen_for_continuation
+        add_response_handler do |response|
+          if awaiting_continuation? && response.is_a?(Net::IMAP::ContinuationRequest)
+            @awaiting_continuation.receive_event response
+          end
+        end
+      end
+
+      # If nothing is listening for continuations from the server,
+      # execute the block immediately.
+      # 
+      # Otherwise add the block to the queue.
+      #
+      # When we have replied to the server's continuation response,
+      # the queue will be emptied in-order.
+      #
+      def when_not_awaiting_continuation(&block)
+        if awaiting_continuation?
+          @awaiting_continuation.bothback{ when_not_awaiting_continuation(&block) }
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/em-imap/listener.rb

@@ -0,0 +1,154 @@
+module EventMachine
+  module IMAP
+    # A Listener is a cancellable subscriber to an event stream, they are used
+    # to provide control-flow abstraction throughout em-imap.
+    #
+    # They can be thought of as a deferrable with two internal phases:
+    #
+    #   deferrable: create |-------------------------------> [succeed/fail]
+    #   listener:   create |---[listening]----> [stop]-----> [succeed/fail]
+    #
+    # A stopback may call succeed or fail immediately, or after performing
+    # necessary cleanup.
+    #
+    # There are several hooks to which you can subscribe:
+    #
+    #  #listen(&block): Each time .receive_event is called, the block will
+    #  be called.
+    #
+    #  #stopback(&block): When someone calls .stop on the listener, this block
+    #  will be called.
+    #
+    #  #callback(&block), #errback(&block), #bothback(&block): Inherited from
+    #  deferrables (and enhanced by deferrable gratification).
+    #
+    #
+    # And the corresponding methods for sending messages to subscribers:
+    #
+    #  #receive_event(*args): Passed onto blocks registered by listen.
+    #
+    #  #stop(*args): Calls all the stopbacks.
+    #  
+    #  #succeed(*args), #fail(*args): Inherited from deferrables.
+    #
+    #
+    # Listeners are defined in such a way that it's most natural to create them
+    # from deep within a library, and return them to the original caller via
+    # layers of abstraction.
+    #
+    # To this end, they also have a .transform method which can be used to
+    # create a new listener that acts the same as the old listener, but which
+    # succeeds with a different return value. The call to .stop is propagated
+    # from the new listener to the old, but calls to .receive_event, .succeed
+    # and .fail are propagated from the old to the new.
+    #
+    # This slightly contrived example shows how listeners can be used with three
+    # levels of abstraction juxtaposed:
+    #
+    # def receive_characters
+    #   Listener.new.tap do |listener|
+    #
+    #     continue = true
+    #     listener.stopback{ continue = false }
+    #
+    #     EM::next_tick do
+    #       while continue
+    #         if key = $stdin.read(1)
+    #           listener.receive_event key
+    #         else
+    #           continue = false
+    #           listener.fail EOFError.new
+    #         end
+    #       end
+    #       listener.succeed
+    #     end
+    #   end
+    # end
+    #
+    # def get_line
+    #   buffer = ""
+    #   listener = receive_characters.listen do |key|
+    #     buffer << key
+    #     listener.stop if key == "\n"
+    #   end.transform do
+    #     buffer
+    #   end
+    # end
+    #
+    # EM::run do
+    #   get_line.callback do |line|
+    #     puts "DONE: #{line}"
+    #   end.errback do |e|
+    #     puts [e] + e.backtrace
+    #   end.bothback do
+    #     EM::stop
+    #   end
+    # end
+    #
+    module ListeningDeferrable
+      include EM::Deferrable
+      DG.enhance!(self)
+
+      # Register a block to be called when receive_event is called.
+      def listen(&block)
+        listeners << block
+        self
+      end
+
+      # Pass arguments onto any blocks registered with listen.
+      def receive_event(*args, &block)
+        listeners.each{ |l| l.call *args, &block }
+      end
+
+      # Register a block to be called when the ListeningDeferrable is stopped.
+      def stopback(&block)
+        stop_deferrable.callback &block
+        self
+      end
+
+      # Initiate shutdown.
+      def stop(*args, &block)
+        stop_deferrable.succeed *args, &block
+      end
+
+      # A re-implementation of DG::Combinators#transform.
+      #
+      # The returned listener will succeed at the same time as this listener,
+      # but the value with which it succeeds will have been transformed using
+      # the given block. If this listener fails, the returned listener will
+      # also fail with the same arguments.
+      #
+      # In addition, any events that this listener receives will be forwarded
+      # to the new listener, and the stop method of the new listener will also
+      # stop the existing listener.
+      #
+      # NOTE: This does not affect the implementation of bind! which still
+      # returns a normal deferrable, not a listener.
+      #
+      def transform(&block)
+        Listener.new.tap do |listener|
+          self.callback do |*args|
+            listener.succeed block.call(*args)
+          end.errback do |*args|
+            listener.fail *args
+          end.listen do |*args|
+            listener.receive_event *args
+          end
+
+          listener.stopback{ self.stop }
+        end
+      end
+
+      private
+      def listeners; @listeners ||= []; end
+      def stop_deferrable; @stop_deferrable ||= DefaultDeferrable.new; end
+    end
+
+    class Listener
+      include ListeningDeferrable
+      def initialize(&block)
+        listen &block if block_given?
+      end
+    end
+  end
+end