✨ Add response_handlers kwarg to Net::IMAP.new

This ensures every server response is handled, including the greeting.

Author: nevans

lib/net/imap.rb

@@ -160,8 +160,9 @@ module Net
   # Use paginated or limited versions of commands whenever possible.
   #
   # Use #add_response_handler to handle responses after each one is received.
-  # Use #extract_responses, #clear_responses, or #responses (with a block) to
-  # prune responses.
+  # Use the +response_handlers+ argument to ::new to assign response handlers
+  # before the receiver thread is started.  Use #extract_responses,
+  # #clear_responses, or #responses (with a block) to prune responses.
   #
   # == Errors
   #
@@ -1996,6 +1997,11 @@ def idle_done
     #     end
     #   }
     #
+    # Response handlers can also be added when the client is created before the
+    # receiver thread is started, by the +response_handlers+ argument to ::new.
+    # This ensures every server response is handled, including the #greeting.
+    #
+    # Related: #remove_response_handler, #response_handlers
     def add_response_handler(handler = nil, &block)
       raise ArgumentError, "two Procs are passed" if handler && block
       @response_handlers.push(block || handler)
@@ -2031,6 +2037,12 @@ def remove_response_handler(handler)
     #         OpenSSL::SSL::SSLContext#set_params as parameters.
     # open_timeout:: Seconds to wait until a connection is opened
     # idle_response_timeout:: Seconds to wait until an IDLE response is received
+    # response_handlers:: A list of response handlers to be added before the
+    #                     receiver thread is started.  This ensures every server
+    #                     response is handled, including the #greeting.  Note
+    #                     that the greeting is handled in the current thread,
+    #                     but all other responses are handled in the receiver
+    #                     thread.
     #
     # The most common errors are:
     #
@@ -2073,6 +2085,7 @@ def initialize(host, port_or_options = {},
         @responses = Hash.new([].freeze)
         @tagged_responses = {}
         @response_handlers = []
+        options[:response_handlers]&.each do |h| add_response_handler(h) end
         @tagged_response_arrival = new_cond
         @continued_command_tag = nil
         @continuation_request_arrival = new_cond
@@ -2089,6 +2102,7 @@ def initialize(host, port_or_options = {},
         if @greeting.name == "BYE"
           raise ByeResponseError, @greeting
         end
+        @response_handlers.each do |handler| handler.call(@greeting) end
 
         @client_thread = Thread.current
         @receiver_thread = Thread.start {

test/net/imap/test_imap_response_handlers.rb

@@ -50,4 +50,41 @@ def teardown
     end
   end
 
+  test "::new with response_handlers kwarg" do
+    greeting = nil
+    expunges = []
+    alerts   = []
+    untagged = 0
+    handler0 = ->{ greeting ||= _1 }
+    handler1 = ->{ alerts   << _1.data.text if _1 in {data: {code: {name: "ALERT"}}} }
+    handler2 = ->{ expunges << _1.data if _1 in {name: "EXPUNGE"} }
+    handler3 = ->{ untagged += 1 if _1.is_a?(Net::IMAP::UntaggedResponse) }
+    response_handlers = [handler0, handler1, handler2, handler3]
+
+    run_fake_server_in_thread do |server|
+      port = server.port
+      imap = Net::IMAP.new("localhost", port:, response_handlers:)
+      assert_equal response_handlers, imap.response_handlers
+      refute_same  response_handlers, imap.response_handlers
+
+      # handler0 recieved the greeting and handler3 counted it
+      assert_equal imap.greeting, greeting
+      assert_equal 1, untagged
+
+      server.on("NOOP") do |resp|
+        resp.untagged "1 EXPUNGE"
+        resp.untagged "1 EXPUNGE"
+        resp.untagged "OK [ALERT] The first alert."
+        resp.done_ok  "[ALERT] Did you see the alert?"
+      end
+
+      imap.noop
+      assert_equal 4, untagged
+      assert_equal [1, 1], expunges # from handler2
+      assert_equal ["The first alert.", "Did you see the alert?"], alerts
+    ensure
+      imap&.logout! unless imap&.disconnected?
+    end
+  end
+
 end