net-imap 0.4.19 → 0.4.24

data/lib/net/imap.rb

@@ -43,10 +43,16 @@ module Net
   # To work on the messages within a mailbox, the client must
   # first select that mailbox, using either #select or #examine
   # (for read-only access).  Once the client has successfully
-  # selected a mailbox, they enter the "_selected_" state, and that
+  # selected a mailbox, they enter the +selected+ state, and that
   # mailbox becomes the _current_ mailbox, on which mail-item
   # related commands implicitly operate.
   #
+  # === Connection state
+  #
+  # Once an IMAP connection is established, the connection is in one of four
+  # states: <tt>not authenticated</tt>, +authenticated+, +selected+, and
+  # +logout+.  Most commands are valid only in certain states.
+  #
   # === Sequence numbers and UIDs
   #
   # Messages have two sorts of identifiers: message sequence
@@ -199,6 +205,42 @@ module Net
   #
   # This script invokes the FETCH command and the SEARCH command concurrently.
   #
+  # When running multiple commands, care must be taken to avoid ambiguity.  For
+  # example, SEARCH responses are ambiguous about which command they are
+  # responding to, so search commands should not run simultaneously, unless the
+  # server supports +ESEARCH+ {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731] or
+  # IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].  See {RFC9051
+  # §5.5}[https://www.rfc-editor.org/rfc/rfc9051.html#section-5.5] for
+  # other examples of command sequences which should not be pipelined.
+  #
+  # == Unbounded memory use
+  #
+  # Net::IMAP reads server responses in a separate receiver thread per client.
+  # Unhandled response data is saved to #responses, and response_handlers run
+  # inside the receiver thread.  See the list of methods for {handling server
+  # responses}[rdoc-ref:Net::IMAP@Handling+server+responses], below.
+  #
+  # Because the receiver thread continuously reads and saves new responses, some
+  # scenarios must be careful to avoid unbounded memory use:
+  #
+  # * Commands such as #list or #fetch can have an enormous number of responses.
+  # * Commands such as #fetch can result in an enormous size per response.
+  # * Long-lived connections will gradually accumulate unsolicited server
+  #   responses, especially +EXISTS+, +FETCH+, and +EXPUNGE+ responses.
+  # * A buggy or untrusted server could send inappropriate responses, which
+  #   could be very numerous, very large, and very rapid.
+  #
+  # Use paginated or limited versions of commands whenever possible.
+  #
+  # Use Config#max_response_size to impose a limit on incoming server responses
+  # as they are being read.  <em>This is especially important for untrusted
+  # servers.</em>
+  #
+  # Use #add_response_handler to handle responses after each one is received.
+  # 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
   #
   # An \IMAP server can send three different types of responses to indicate
@@ -260,8 +302,9 @@ module Net
   #
   # - Net::IMAP.new: Creates a new \IMAP client which connects immediately and
   #   waits for a successful server greeting before the method returns.
+  # - #connection_state: Returns the connection state.
   # - #starttls: Asks the server to upgrade a clear-text connection to use TLS.
-  # - #logout: Tells the server to end the session. Enters the "_logout_" state.
+  # - #logout: Tells the server to end the session.  Enters the +logout+ state.
   # - #disconnect: Disconnects the connection (without sending #logout first).
   # - #disconnected?: True if the connection has been closed.
   #
@@ -317,37 +360,36 @@ module Net
   #   <em>In general, #capable? should be used rather than explicitly sending a
   #   +CAPABILITY+ command to the server.</em>
   # - #noop: Allows the server to send unsolicited untagged #responses.
-  # - #logout: Tells the server to end the session. Enters the "_logout_" state.
+  # - #logout: Tells the server to end the session. Enters the +logout+ state.
   #
   # ==== Not Authenticated state
   #
   # In addition to the commands for any state, the following commands are valid
-  # in the "<em>not authenticated</em>" state:
+  # in the +not_authenticated+ state:
   #
   # - #starttls: Upgrades a clear-text connection to use TLS.
   #
   #   <em>Requires the +STARTTLS+ capability.</em>
   # - #authenticate: Identifies the client to the server using the given
   #   {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-  #   and credentials.  Enters the "_authenticated_" state.
+  #   and credentials.  Enters the +authenticated+ state.
   #
   #   <em>The server should list <tt>"AUTH=#{mechanism}"</tt> capabilities for
   #   supported mechanisms.</em>
   # - #login: Identifies the client to the server using a plain text password.
-  #   Using #authenticate is generally preferred.  Enters the "_authenticated_"
-  #   state.
+  #   Using #authenticate is preferred.  Enters the +authenticated+ state.
   #
   #   <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
   #
   # ==== Authenticated state
   #
   # In addition to the commands for any state, the following commands are valid
-  # in the "_authenticated_" state:
+  # in the +authenticated+ state:
   #
   # - #enable: Enables backwards incompatible server extensions.
   #   <em>Requires the +ENABLE+ or +IMAP4rev2+ capability.</em>
-  # - #select:  Open a mailbox and enter the "_selected_" state.
-  # - #examine: Open a mailbox read-only, and enter the "_selected_" state.
+  # - #select:  Open a mailbox and enter the +selected+ state.
+  # - #examine: Open a mailbox read-only, and enter the +selected+ state.
   # - #create: Creates a new mailbox.
   # - #delete: Permanently remove a mailbox.
   # - #rename: Change the name of a mailbox.
@@ -369,12 +411,12 @@ module Net
   #
   # ==== Selected state
   #
-  # In addition to the commands for any state and the "_authenticated_"
-  # commands, the following commands are valid in the "_selected_" state:
+  # In addition to the commands for any state and the +authenticated+
+  # commands, the following commands are valid in the +selected+ state:
   #
-  # - #close: Closes the mailbox and returns to the "_authenticated_" state,
+  # - #close: Closes the mailbox and returns to the +authenticated+ state,
   #   expunging deleted messages, unless the mailbox was opened as read-only.
-  # - #unselect: Closes the mailbox and returns to the "_authenticated_" state,
+  # - #unselect: Closes the mailbox and returns to the +authenticated+ state,
   #   without expunging any messages.
   #   <em>Requires the +UNSELECT+ or +IMAP4rev2+ capability.</em>
   # - #expunge: Permanently removes messages which have the Deleted flag set.
@@ -395,7 +437,7 @@ module Net
   #
   # ==== Logout state
   #
-  # No \IMAP commands are valid in the "_logout_" state.  If the socket is still
+  # No \IMAP commands are valid in the +logout+ state.  If the socket is still
   # open, Net::IMAP will close it after receiving server confirmation.
   # Exceptions will be raised by \IMAP commands that have already started and
   # are waiting for a response, as well as any that are called after logout.
@@ -418,6 +460,9 @@ module Net
   #   +LITERAL-+, and +SPECIAL-USE+.</em>
   #
   # ==== RFC2087: +QUOTA+
+  # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
+  # - Obsoleted by <tt>QUOTA=RES-*</tt> [RFC9208[https://www.rfc-editor.org/rfc/rfc9208]],
+  #   although the commands are backward compatible.
   # - #getquota: returns the resource usage and limits for a quota root
   # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
   #   their resource usage and limits.
@@ -449,7 +494,7 @@ module Net
   # ==== RFC3691: +UNSELECT+
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
-  # - #unselect: Closes the mailbox and returns to the "_authenticated_" state,
+  # - #unselect: Closes the mailbox and returns to the +authenticated+ state,
   #   without expunging any messages.
   #
   # ==== RFC4314: +ACL+
@@ -530,6 +575,16 @@ module Net
   #   See FetchData#emailid and FetchData#emailid.
   # - Updates #status with support for the +MAILBOXID+ status attribute.
   #
+  # ==== RFC9208: <tt>QUOTA=RES-*</tt>
+  # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
+  # - Obsoletes the +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+  #   extension and provides strict semantics for different resource types.
+  # - #getquota: returns the resource usage and limits for a quota root
+  # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
+  #   their resource usage and limits.
+  # - #setquota: sets the resource limits for a given quota root.
+  # - Updates #status with <tt>"DELETED"</tt> and +DELETED-STORAGE+ attributes.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
@@ -639,14 +694,13 @@ module Net
   #
   # === \IMAP Extensions
   #
-  # [QUOTA[https://tools.ietf.org/html/rfc9208]]::
-  #   Melnikov, A., "IMAP QUOTA Extension", RFC 9208, DOI 10.17487/RFC9208,
-  #   March 2022, <https://www.rfc-editor.org/info/rfc9208>.
+  # [QUOTA[https://www.rfc-editor.org/rfc/rfc2087]]::
+  #   Myers, J., "IMAP4 QUOTA extension", RFC 2087, DOI 10.17487/RFC2087,
+  #   January 1997, <https://www.rfc-editor.org/info/rfc2087>.
   #
-  #   <em>Note: obsoletes</em>
-  #   RFC-2087[https://tools.ietf.org/html/rfc2087]<em> (January 1997)</em>.
-  #   <em>Net::IMAP does not fully support the RFC9208 updates yet.</em>
-  # [IDLE[https://tools.ietf.org/html/rfc2177]]::
+  #   *NOTE*: _obsoleted_ by RFC9208[https://www.rfc-editor.org/rfc/rfc9208]
+  #   (March 2022).
+  # [IDLE[https://www.rfc-editor.org/rfc/rfc2177]]::
   #   Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177,
   #   June 1997, <https://www.rfc-editor.org/info/rfc2177>.
   # [NAMESPACE[https://tools.ietf.org/html/rfc2342]]::
@@ -697,9 +751,15 @@ module Net
   #   Gondwana, B., Ed., "IMAP Extension for Object Identifiers",
   #   RFC 8474, DOI 10.17487/RFC8474, September 2018,
   #   <https://www.rfc-editor.org/info/rfc8474>.
+  # [{QUOTA=RES-*}[https://www.rfc-editor.org/rfc/rfc9208]]::
+  #   Melnikov, A., "IMAP QUOTA Extension", RFC 9208, DOI 10.17487/RFC9208,
+  #   March 2022, <https://www.rfc-editor.org/info/rfc9208>.
+  #
+  #   Obsoletes RFC2087[https://www.rfc-editor.org/rfc/rfc2087].
   #
   # === IANA registries
   # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
+  #   * {IMAP Quota Resource Types}[http://www.iana.org/assignments/imap4-capabilities#imap-capabilities-2]
   # * {IMAP Response Codes}[https://www.iana.org/assignments/imap-response-codes/imap-response-codes.xhtml]
   # * {IMAP Mailbox Name Attributes}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml]
   # * {IMAP and JMAP Keywords}[https://www.iana.org/assignments/imap-jmap-keywords/imap-jmap-keywords.xhtml]
@@ -719,7 +779,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.19"
+    VERSION = "0.4.24"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -727,6 +787,7 @@ module Net
       "UTF8=ONLY" => "UTF8=ACCEPT",
     }.freeze
 
+    autoload :ResponseReader, File.expand_path("imap/response_reader", __dir__)
     autoload :SASL,        File.expand_path("imap/sasl",         __dir__)
     autoload :SASLAdapter, File.expand_path("imap/sasl_adapter", __dir__)
     autoload :StringPrep,  File.expand_path("imap/stringprep",   __dir__)
@@ -741,9 +802,11 @@ module Net
     def self.config; Config.global end
 
     # Returns the global debug mode.
+    # Delegates to {Net::IMAP.config.debug}[rdoc-ref:Config#debug].
     def self.debug; config.debug end
 
     # Sets the global debug mode.
+    # Delegates to {Net::IMAP.config.debug=}[rdoc-ref:Config#debug=].
     def self.debug=(val)
       config.debug = val
     end
@@ -764,7 +827,7 @@ module Net
       alias default_ssl_port default_tls_port
     end
 
-    # Returns the initial greeting the server, an UntaggedResponse.
+    # Returns the initial greeting sent by the server, an UntaggedResponse.
     attr_reader :greeting
 
     # The client configuration.  See Net::IMAP::Config.
@@ -773,13 +836,28 @@ module Net
     # Net::IMAP.config.
     attr_reader :config
 
-    # Seconds to wait until a connection is opened.
-    # If the IMAP object cannot open a connection within this time,
-    # it raises a Net::OpenTimeout exception. The default value is 30 seconds.
-    def open_timeout; config.open_timeout end
+    ##
+    # :attr_reader: open_timeout
+    # Seconds to wait until a connection is opened.  Also used by #starttls.
+    # Delegates to {config.open_timeout}[rdoc-ref:Config#open_timeout].
 
+    ##
+    # :attr_reader: idle_response_timeout
     # Seconds to wait until an IDLE response is received.
-    def idle_response_timeout; config.idle_response_timeout end
+    # Delegates to {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout].
+
+    ##
+    # :attr_accessor: max_response_size
+    #
+    # The maximum allowed server response size, in bytes.
+    # Delegates to {config.max_response_size}[rdoc-ref:Config#max_response_size].
+
+    # :stopdoc:
+    def open_timeout;           config.open_timeout            end
+    def idle_response_timeout;  config.idle_response_timeout   end
+    def max_response_size;      config.max_response_size       end
+    def max_response_size=(val) config.max_response_size = val end
+    # :startdoc:
 
     # The hostname this client connected to
     attr_reader :host
@@ -835,6 +913,12 @@ module Net
     #
     #   See DeprecatedClientOptions.new for deprecated SSL arguments.
     #
+    # [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.
+    #
     # [config]
     #   A Net::IMAP::Config object to use as the basis for #config.  By default,
     #   the global Net::IMAP.config is used.
@@ -906,7 +990,7 @@ module Net
     # [Net::IMAP::ByeResponseError]
     #   Connected to the host successfully, but it immediately said goodbye.
     #
-    def initialize(host, port: nil, ssl:  nil,
+    def initialize(host, port: nil, ssl: nil, response_handlers: nil,
                    config: Config.global, **config_options)
       super()
       # Config options
@@ -929,6 +1013,7 @@ module Net
       @receiver_thread = nil
       @receiver_thread_exception = nil
       @receiver_thread_terminating = false
+      response_handlers&.each do add_response_handler(_1) end
 
       # Client Protocol Sender (including state for currently running commands)
       @tag_prefix = "RUBY"
@@ -944,6 +1029,7 @@ module Net
       # Connection
       @tls_verified = false
       @sock = tcp_socket(@host, @port)
+      @reader = ResponseReader.new(self, @sock)
       start_tls_session if ssl_ctx
       start_imap_connection
 
@@ -1204,6 +1290,10 @@ module Net
     # both successful.  Any error indicates that the connection has not been
     # secured.
     #
+    # After the server agrees to start a TLS connection, this method waits up to
+    # {config.open_timeout}[rdoc-ref:Config#open_timeout] before raising
+    # +Net::OpenTimeout+.
+    #
     # *Note:*
     # >>>
     #   Any #response_handlers added before STARTTLS should be aware that the
@@ -1222,9 +1312,11 @@ module Net
     #
     def starttls(**options)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options)
+      handled = false
       error = nil
       ok = send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
+          handled = true
           clear_cached_capabilities
           clear_responses
           start_tls_session
@@ -1236,6 +1328,13 @@ module Net
         disconnect
         raise error
       end
+      unless handled
+        disconnect
+        raise InvalidResponseError,
+              "STARTTLS handler was bypassed, although server responded %p" % [
+                ok.raw_data.chomp
+              ]
+      end
       ok
     end
 
@@ -1670,12 +1769,18 @@ module Net
     # to both admin and user.  If this mailbox exists, it returns an array
     # containing objects of type MailboxQuotaRoot and MailboxQuota.
     #
+    # *NOTE:* Currently, Net::IMAP only supports +QUOTA+ responses with a single
+    # resource type.  This is usually +STORAGE+, but you may need to verify this
+    # with UntaggedResponse#raw_data.
+    #
     # Related: #getquota, #setquota, MailboxQuotaRoot, MailboxQuota
     #
     # ===== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
     def getquotaroot(mailbox)
       synchronize do
         send_command("GETQUOTAROOT", mailbox)
@@ -1687,41 +1792,59 @@ module Net
     end
 
     # Sends a {GETQUOTA command [RFC2087 §4.2]}[https://www.rfc-editor.org/rfc/rfc2087#section-4.2]
-    # along with specified +mailbox+.  If this mailbox exists, then an array
-    # containing a MailboxQuota object is returned.  This command is generally
-    # only available to server admin.
+    # for the +quota_root+.  If this quota root exists, then an array
+    # containing a MailboxQuota object is returned.
+    #
+    # The names of quota roots that are applicable to a particular mailbox can
+    # be discovered with #getquotaroot.
+    #
+    # *NOTE:* Currently, Net::IMAP only supports +QUOTA+ responses with a single
+    # resource type.  This is usually +STORAGE+, but you may need to verify this
+    # with UntaggedResponse#raw_data.
     #
     # Related: #getquotaroot, #setquota, MailboxQuota
     #
     # ===== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
-    def getquota(mailbox)
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
+    def getquota(quota_root)
       synchronize do
-        send_command("GETQUOTA", mailbox)
+        send_command("GETQUOTA", quota_root)
         clear_responses("QUOTA")
       end
     end
 
     # Sends a {SETQUOTA command [RFC2087 §4.1]}[https://www.rfc-editor.org/rfc/rfc2087#section-4.1]
-    # along with the specified +mailbox+ and +quota+.  If +quota+ is nil, then
-    # +quota+ will be unset for that mailbox.  Typically one needs to be logged
-    # in as a server admin for this to work.
+    # along with the specified +quota_root+ and +storage_limit+.  If
+    # +storage_limit+ is +nil+, resource limits are unset for that quota root.
+    # If +storage_limit+ is a number, it sets the +STORAGE+ resource limit.
+    #
+    #   imap.setquota "#user/alice", 100
+    #   imap.getquota "#user/alice"
+    #   # => [#<struct Net::IMAP::MailboxQuota mailbox="#user/alice" usage=54 quota=100>]
+    #
+    # Typically one needs to be logged in as a server admin for this to work.
+    #
+    # *NOTE:* Currently, Net::IMAP only supports setting +STORAGE+ quota limits.
     #
     # Related: #getquota, #getquotaroot
     #
     # ===== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
-    def setquota(mailbox, quota)
-      if quota.nil?
-        data = '()'
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or both +QUOTASET+ and a capability prefixed with
+    # <tt>QUOTA=RES-*</tt> {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208]
+    # for each supported resource type.
+    def setquota(quota_root, storage_limit)
+      if storage_limit.nil?
+        list = []
       else
-        data = '(STORAGE ' + quota.to_s + ')'
+        list = ["STORAGE", Integer(storage_limit)]
       end
-      send_command("SETQUOTA", mailbox, RawData.new(data))
+      send_command("SETQUOTA", quota_root, list)
     end
 
     # Sends a {SETACL command [RFC4314 §3.1]}[https://www.rfc-editor.org/rfc/rfc4314#section-3.1]
@@ -1828,7 +1951,10 @@ module Net
     # <tt>STATUS=SIZE</tt>
     # {[RFC8483]}[https://www.rfc-editor.org/rfc/rfc8483.html].
     #
-    # +DELETED+ requires the server's capabilities to include +IMAP4rev2+.
+    # +DELETED+ must be supported when the server's capabilities includes
+    # +IMAP4rev2+.
+    # or <tt>QUOTA=RES-MESSAGES</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208.html].
     #
     # +HIGHESTMODSEQ+ requires the server's capabilities to include +CONDSTORE+
     # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
@@ -1977,6 +2103,14 @@ module Net
     #
     # ===== Search criteria
     #
+    # >>>
+    #   When +criteria+ is an Array, elements in the array will be validated and
+    #   formatted.  When +criteria+ is a String, it will be sent <em>with
+    #   minimal validation and no encoding or formatting</em>.
+    #
+    #   <em>*WARNING:* Although CRLF is prohibited, this is vulnerable to other
+    #   types of attribute injection attack if unvetted user input is used.</em>
+    #
     # For a full list of search criteria,
     # see [{IMAP4rev1 §6.4.4}[https://www.rfc-editor.org/rfc/rfc3501.html#section-6.4.4]],
     # or  [{IMAP4rev2 §6.4.4}[https://www.rfc-editor.org/rfc/rfc9051.html#section-6.4.4]],
@@ -2064,6 +2198,13 @@ module Net
     #
     # +attr+ is a list of attributes to fetch; see the documentation
     # for FetchData for a list of valid attributes.
+    # >>>
+    #   When +attr+ is a String, it will be sent <em>with minimal validation and
+    #   no encoding or formatting</em>.  When +attr+ is an Array, each String in
+    #   +attr+ will be sent this way.
+    #
+    #   <em>*WARNING:* Although CRLF is prohibited, this is vulnerable to other
+    #   types of attribute injection attack if unvetted user input is used.</em>
     #
     # +changedsince+ is an optional integer mod-sequence.  It limits results to
     # messages with a mod-sequence greater than +changedsince+.
@@ -2619,7 +2760,7 @@ module Net
           warn(RESPONSES_DEPRECATION_MSG, uplevel: 1)
         when :frozen_dup
           synchronize {
-            responses = @responses.transform_values(&:freeze)
+            responses = @responses.transform_values { _1.dup.freeze }
             responses.default_proc = nil
             responses.default = [].freeze
             return responses.freeze
@@ -2706,6 +2847,10 @@ module Net
     #     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
@@ -2732,6 +2877,7 @@ module Net
     def start_imap_connection
       @greeting        = get_server_greeting
       @capabilities    = capabilities_from_resp_code @greeting
+      @response_handlers.each do |handler| handler.call(@greeting) end
       @receiver_thread = start_receiver_thread
     rescue Exception
       @sock.close
@@ -2860,23 +3006,10 @@ module Net
     end
 
     def get_response
-      buff = String.new
-      while true
-        s = @sock.gets(CRLF)
-        break unless s
-        buff.concat(s)
-        if /\{(\d+)\}\r\n/n =~ s
-          s = @sock.read($1.to_i)
-          buff.concat(s)
-        else
-          break
-        end
-      end
+      buff = @reader.read_response_buffer
       return nil if buff.length == 0
-      if config.debug?
-        $stderr.print(buff.gsub(/^/n, "S: "))
-      end
-      return @parser.parse(buff)
+      $stderr.print(buff.gsub(/^/n, "S: ")) if config.debug?
+      @parser.parse(buff)
     end
 
     #############################
@@ -2928,6 +3061,7 @@ module Net
           put_string(" ")
           send_data(i, tag)
         end
+        guard_against_tagged_response_skipping_handler!(tag)
         put_string(CRLF)
         if cmd == "LOGOUT"
           @logout_command_tag = tag
@@ -2943,6 +3077,17 @@ module Net
           end
         end
       end
+    rescue InvalidResponseError
+      disconnect
+      raise
+    end
+
+    def guard_against_tagged_response_skipping_handler!(tag)
+      return unless (resp = @tagged_responses[tag])&.name&.upcase == "OK"
+      raise(InvalidResponseError,
+            "Server sent tagged 'OK' before command was finished: %p. " \
+            "This could indicate a malicious server or client-side " \
+            "command injection. Disconnecting." % [resp.raw_data.chomp])
     end
 
     def generate_tag
@@ -3007,7 +3152,7 @@ module Net
     end
 
     def store_internal(cmd, set, attr, flags, unchangedsince: nil)
-      attr = RawData.new(attr) if attr.instance_of?(String)
+      attr = Atom.new(attr) if attr.instance_of?(String)
       args = [MessageSet.new(set)]
       args << ["UNCHANGEDSINCE", Integer(unchangedsince)] if unchangedsince
       args << attr << flags
@@ -3077,6 +3222,7 @@ module Net
       raise "already using SSL" if @sock.kind_of?(OpenSSL::SSL::SSLSocket)
       raise "cannot start TLS without SSLContext" unless ssl_ctx
       @sock = SSLSocket.new(@sock, ssl_ctx)
+      @reader = ResponseReader.new(self, @sock)
       @sock.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
       ssl_socket_connect(@sock, open_timeout)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.19
+  version: 0.4.24
 platform: ruby
 authors:
 - Shugo Maeda
 - nicholas a. evans
 bindir: exe
 cert_chain: []
-date: 2025-02-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -68,6 +68,7 @@ files:
 - lib/net/imap/response_data.rb
 - lib/net/imap/response_parser.rb
 - lib/net/imap/response_parser/parser_utils.rb
+- lib/net/imap/response_reader.rb
 - lib/net/imap/sasl.rb
 - lib/net/imap/sasl/anonymous_authenticator.rb
 - lib/net/imap/sasl/authentication_exchange.rb
@@ -124,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []