net-imap 0.4.12 → 0.5.1

data/lib/net/imap.rb

@@ -288,6 +288,8 @@ module Net
   #   pre-authenticated connection.
   # - #responses: Yields unhandled UntaggedResponse#data and <em>non-+nil+</em>
   #   ResponseCode#data.
+  # - #extract_responses: Removes and returns the responses for which the block
+  #   returns a true value.
   # - #clear_responses: Deletes unhandled data from #responses and returns it.
   # - #add_response_handler: Add a block to be called inside the receiver thread
   #   with every server response.
@@ -717,7 +719,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.12"
+    VERSION = "0.5.1"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -735,14 +737,15 @@ module Net
       include SSL
     end
 
-    # Returns the debug mode.
-    def self.debug
-      return @@debug
-    end
+    # Returns the global Config object
+    def self.config; Config.global end
+
+    # Returns the global debug mode.
+    def self.debug; config.debug end
 
-    # Sets the debug mode.
+    # Sets the global debug mode.
     def self.debug=(val)
-      return @@debug = val
+      config.debug = val
     end
 
     # The default port for IMAP connections, port 143
@@ -764,13 +767,19 @@ module Net
     # Returns the initial greeting the server, an UntaggedResponse.
     attr_reader :greeting
 
+    # The client configuration.  See Net::IMAP::Config.
+    #
+    # By default, the client's local configuration inherits from the global
+    # 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.
-    attr_reader :open_timeout
+    def open_timeout; config.open_timeout end
 
     # Seconds to wait until an IDLE response is received.
-    attr_reader :idle_response_timeout
+    def idle_response_timeout; config.idle_response_timeout end
 
     # The hostname this client connected to
     attr_reader :host
@@ -809,14 +818,40 @@ module Net
     #   If +ssl+ is a hash, it's passed to
     #   {OpenSSL::SSL::SSLContext#set_params}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params];
     #   the keys are names of attribute assignment methods on
-    #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].
+    #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].  For example:
+    #
+    #   [{ca_file}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-ca_file]]
+    #     The path to a file containing a PEM-format CA certificate.
+    #   [{ca_path}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-ca_path]]
+    #     The path to a directory containing CA certificates in PEM format.
+    #   [{min_version}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-min_version-3D]]
+    #     Sets the lower bound on the supported SSL/TLS protocol version. Set to
+    #     an +OpenSSL+ constant such as +OpenSSL::SSL::TLS1_2_VERSION+,
+    #   [{verify_mode}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-verify_mode]]
+    #     SSL session verification mode.  Valid modes include
+    #     +OpenSSL::SSL::VERIFY_PEER+ and +OpenSSL::SSL::VERIFY_NONE+.
+    #
+    #   See {OpenSSL::SSL::SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html] for other valid SSL context params.
     #
-    # [open_timeout]
-    #   Seconds to wait until a connection is opened
-    # [idle_response_timeout]
-    #   Seconds to wait until an IDLE response is received
+    #   See DeprecatedClientOptions.new for deprecated SSL arguments.
     #
-    # See DeprecatedClientOptions.new for deprecated arguments.
+    # [config]
+    #   A Net::IMAP::Config object to use as the basis for #config.  By default,
+    #   the global Net::IMAP.config is used.
+    #
+    #   >>>
+    #     *NOTE:* +config+ does not set #config directly---it sets the _parent_
+    #     config for inheritance.  Every client creates its own unique #config.
+    #
+    #   All other keyword arguments are forwarded to Net::IMAP::Config.new, to
+    #   initialize the client's #config. For example:
+    #
+    #   [{open_timeout}[rdoc-ref:Config#open_timeout]]
+    #     Seconds to wait until a connection is opened
+    #   [{idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]]
+    #     Seconds to wait until an IDLE response is received
+    #
+    #   See Net::IMAP::Config for other valid options.
     #
     # ==== Examples
     #
@@ -872,13 +907,12 @@ module Net
     #   Connected to the host successfully, but it immediately said goodbye.
     #
     def initialize(host, port: nil, ssl:  nil,
-                   open_timeout: 30, idle_response_timeout: 5)
+                   config: Config.global, **config_options)
       super()
       # Config options
       @host = host
+      @config = Config.new(config, **config_options)
       @port = port || (ssl ? SSL_PORT : PORT)
-      @open_timeout = Integer(open_timeout)
-      @idle_response_timeout = Integer(idle_response_timeout)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(ssl)
 
       # Basic Client State
@@ -889,7 +923,7 @@ module Net
       @capabilities = nil
 
       # Client Protocol Receiver
-      @parser = ResponseParser.new
+      @parser = ResponseParser.new(config: @config)
       @responses = Hash.new {|h, k| h[k] = [] }
       @response_handlers = []
       @receiver_thread = nil
@@ -912,9 +946,6 @@ module Net
       @sock = tcp_socket(@host, @port)
       start_tls_session if ssl_ctx
       start_imap_connection
-
-      # DEPRECATED: to remove in next version
-      @client_thread = Thread.current
     end
 
     # Returns true after the TLS negotiation has completed and the remote
@@ -922,11 +953,6 @@ module Net
     # but peer verification was disabled.
     def tls_verified?; @tls_verified end
 
-    def client_thread # :nodoc:
-      warn "Net::IMAP#client_thread is deprecated and will be removed soon."
-      @client_thread
-    end
-
     # Disconnects from the server.
     #
     # Related: #logout, #logout!
@@ -1198,7 +1224,7 @@ module Net
     end
 
     # :call-seq:
-    #   authenticate(mechanism, *, sasl_ir: true, registry: Net::IMAP::SASL.authenticators, **, &) -> ok_resp
+    #   authenticate(mechanism, *, sasl_ir: config.sasl_ir, registry: Net::IMAP::SASL.authenticators, **, &) -> ok_resp
     #
     # Sends an {AUTHENTICATE command [IMAP4rev1 §6.2.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.2]
     # to authenticate the client.  If successful, the connection enters the
@@ -1207,7 +1233,11 @@ module Net
     # +mechanism+ is the name of the \SASL authentication mechanism to be used.
     #
     # +sasl_ir+ allows or disallows sending an "initial response" (see the
-    # +SASL-IR+ capability, below).
+    # +SASL-IR+ capability, below).  Defaults to the #config value for
+    # {sasl_ir}[rdoc-ref:Config#sasl_ir], which defaults to +true+.
+    #
+    # The +registry+ kwarg can be used to select the mechanism implementation
+    # from a custom registry.  See SASL.authenticator and SASL::Authenticators.
     #
     # All other arguments are forwarded to the registered SASL authenticator for
     # the requested mechanism.  <em>The documentation for each individual
@@ -1303,27 +1333,9 @@ module Net
     # Previously cached #capabilities will be cleared when this method
     # completes.  If the TaggedResponse to #authenticate includes updated
     # capabilities, they will be cached.
-    def authenticate(mechanism, *creds, sasl_ir: true, **props, &callback)
-      mechanism = mechanism.to_s.tr("_", "-").upcase
-      authenticator = SASL.authenticator(mechanism, *creds, **props, &callback)
-      cmdargs = ["AUTHENTICATE", mechanism]
-      if sasl_ir && capable?("SASL-IR") && auth_capable?(mechanism) &&
-          authenticator.respond_to?(:initial_response?) &&
-          authenticator.initial_response?
-        response = authenticator.process(nil)
-        cmdargs << (response.empty? ? "=" : [response].pack("m0"))
-      end
-      result = send_command_with_continuations(*cmdargs) {|data|
-        challenge = data.unpack1("m")
-        response  = authenticator.process challenge
-        [response].pack("m0")
-      }
-      if authenticator.respond_to?(:done?) && !authenticator.done?
-        logout!
-        raise SASL::AuthenticationIncomplete, result
-      end
-      @capabilities = capabilities_from_resp_code result
-      result
+    def authenticate(*args, sasl_ir: config.sasl_ir, **props, &callback)
+      sasl_adapter.authenticate(*args, sasl_ir: sasl_ir, **props, &callback)
+        .tap { @capabilities = capabilities_from_resp_code _1 }
     end
 
     # Sends a {LOGIN command [IMAP4rev1 §6.2.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.3]
@@ -1343,13 +1355,9 @@ module Net
     # ===== Capabilities
     #
     # An IMAP client MUST NOT call #login when the server advertises the
-    # +LOGINDISABLED+ capability.
-    #
-    #    if imap.capability? "LOGINDISABLED"
-    #      raise "Remote server has disabled the login command"
-    #    else
-    #      imap.login username, password
-    #    end
+    # +LOGINDISABLED+ capability.  By default, Net::IMAP will raise a
+    # LoginDisabledError when that capability is present.  See
+    # Config#enforce_logindisabled.
     #
     # Server capabilities may change after #starttls, #login, and #authenticate.
     # Cached capabilities _must_ be invalidated after this method completes.
@@ -1357,6 +1365,9 @@ module Net
     # ResponseCode.
     #
     def login(user, password)
+      if enforce_logindisabled? && capability?("LOGINDISABLED")
+        raise LoginDisabledError
+      end
       send_command("LOGIN", user, password)
         .tap { @capabilities = capabilities_from_resp_code _1 }
     end
@@ -1913,82 +1924,274 @@ module Net
     # [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]].
     def uid_expunge(uid_set)
       synchronize do
-        send_command("UID EXPUNGE", MessageSet.new(uid_set))
+        send_command("UID EXPUNGE", SequenceSet.new(uid_set))
         clear_responses("EXPUNGE")
       end
     end
 
-    # Sends a {SEARCH command [IMAP4rev1 §6.4.4]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.4]
-    # to search the mailbox for messages that match the given searching
-    # criteria, and returns message sequence numbers.  +keys+ can either be a
-    # string holding the entire search string, or a single-dimension array of
-    # search keywords and arguments.
+    # :call-seq:
+    #   search(criteria, charset = nil) -> result
     #
-    # Returns a SearchResult object.  SearchResult inherits from Array (for
+    # Sends a {SEARCH command [IMAP4rev1 §6.4.4]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.4]
+    # to search the mailbox for messages that match the given search +criteria+,
+    # and returns a SearchResult.  SearchResult inherits from Array (for
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
     #
+    # +criteria+ is one or more search keys and their arguments, which may be
+    # provided as an array or a string.
+    # See {"Search criteria"}[rdoc-ref:#search@Search+criteria], below.
+    #
+    # * When +criteria+ is an array, each member is a +SEARCH+ command argument:
+    #   * Any SequenceSet sends SequenceSet#valid_string.
+    #     These types are converted to SequenceSet for validation and encoding:
+    #     * +Set+
+    #     * +Range+
+    #     * <tt>-1</tt> and +:*+ -- both translate to <tt>*</tt>
+    #     * responds to +#to_sequence_set+
+    #     * +Array+, when each element is one of the above types, a positive
+    #       +Integer+, a sequence-set formatted +String+, or a deeply nested
+    #       +Array+ of these same types.
+    #   * Any +String+ is sent verbatim when it is a valid \IMAP atom,
+    #     and encoded as an \IMAP quoted or literal string otherwise.
+    #   * Any other nested +Array+ is encoded as a parenthesized list, to group
+    #     multiple search keys (e.g., for use with +OR+ and +NOT+).
+    #   * Any other +Integer+ (besides <tt>-1</tt>) will be sent as +#to_s+.
+    #   * +Date+ objects will be encoded as an \IMAP date (see ::encode_date).
+    #
+    # * When +criteria+ is a string, it will be sent directly to the server
+    #   <em>without any validation or encoding</em>.  *WARNING:* This is
+    #   vulnerable to injection attacks when external inputs are used.
+    #
+    # +charset+ is the name of the {registered character
+    # set}[https://www.iana.org/assignments/character-sets/character-sets.xhtml]
+    # used by strings in the search +criteria+.  When +charset+ isn't specified,
+    # either <tt>"US-ASCII"</tt> or <tt>"UTF-8"</tt> is assumed, depending on
+    # the server's capabilities.  +charset+ may be sent inside +criteria+
+    # instead of as a separate argument.
+    #
     # Related: #uid_search
     #
-    # ===== Search criteria
+    # ===== For example:
+    #
+    #   p imap.search(["SUBJECT", "hello", "NOT", "SEEN"])
+    #   #=> [1, 6, 7, 8]
+    #
+    # The following searches send the exact same command to the server:
+    #
+    #    # criteria array, charset arg
+    #    imap.search(["OR", "UNSEEN", %w(FLAGGED SUBJECT foo)], "UTF-8")
+    #    # criteria string, charset arg
+    #    imap.search("OR UNSEEN (FLAGGED SUBJECT foo)", "UTF-8")
+    #    # criteria array contains charset arg
+    #    imap.search([*%w[CHARSET UTF-8], "OR", "UNSEEN", %w(FLAGGED SUBJECT foo)])
+    #    # criteria string contains charset arg
+    #    imap.search("CHARSET UTF-8 OR UNSEEN (FLAGGED SUBJECT foo)")
     #
-    # For a full list of search criteria,
+    # ===== Search keys
+    #
+    # For full definitions of the standard 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]],
     # in addition to documentation for
-    # any [CAPABILITIES[https://www.iana.org/assignments/imap-capabilities/imap-capabilities.xhtml]]
-    # reported by #capabilities which may define additional search filters, e.g:
+    # any #capabilities which may define additional search filters, such as
     # +CONDSTORE+, +WITHIN+, +FILTERS+, <tt>SEARCH=FUZZY</tt>, +OBJECTID+, or
-    # +SAVEDATE+.  The following are some common search criteria:
+    # +SAVEDATE+.
+    #
+    # With the exception of <em>sequence-set</em> and <em>parenthesized
+    # list</em>, all search keys are composed of prefix label with zero or more
+    # arguments.  The number and type of arguments is specific to each search
+    # key.
+    #
+    # +ALL+::
+    #   Matches every message in the mailbox.
+    #
+    # (_search-key_ _search-key_...)::
+    #   Combines one or more _search-key_ arguments to match
+    #   messages which match all contained search keys.  Useful for +OR+, +NOT+,
+    #   and other search keys with _search-key_ arguments.
+    #
+    #   _Note:_ this search key has no label.
+    #
+    # +OR+ _search-key_ _search-key_::
+    #   Matches messages which match either _search-key_ argument.
+    #
+    # +NOT+ _search-key_::
+    #   Matches messages which do not match _search-key_.
+    #
+    # _sequence-set_::
+    #   Matches messages with message sequence numbers in _sequence-set_.
+    #
+    #   _Note:_ this search key has no label.
+    #
+    #   <em>+UIDONLY+ must *not* be enabled.</em>
+    #   {[RFC9586]}[https://www.rfc-editor.org/rfc/rfc9586.html]
+    #
+    # +UID+ _sequence-set_::
+    #   Matches messages with a UID in _sequence-set_.
+    #
+    # +ANSWERED+::
+    # +UNANSWERED+::
+    #   Matches messages with or without the <tt>\\Answered</tt> flag.
+    # +DELETED+::
+    # +UNDELETED+::
+    #   Matches messages with or without the <tt>\\Deleted</tt> flag.
+    # +DRAFT+::
+    # +UNDRAFT+::
+    #   Matches messages with or without the <tt>\\Draft</tt> flag.
+    # +FLAGGED+::
+    # +UNFLAGGED+::
+    #   Matches messages with or without the <tt>\\Flagged</tt> flag.
+    # +SEEN+::
+    # +UNSEEN+::
+    #   Matches messages with or without the <tt>\\Seen</tt> flag.
+    #
+    # +KEYWORD+ _keyword_::
+    # +UNKEYWORD+ _keyword_::
+    #   Matches messages with or without the specified _keyword_.
+    #
+    # +BCC+ _substring_::
+    #   Matches when _substring_ is in the envelope's BCC field.
+    # +CC+ _substring_::
+    #   Matches when _substring_ is in the envelope's CC field.
+    # +FROM+ _substring_::
+    #   Matches when _substring_ is in the envelope's FROM field.
+    # +SUBJECT+ _substring_::
+    #   Matches when _substring_ is in the envelope's SUBJECT field.
+    # +TO+ _substring_::
+    #   Matches when _substring_ is in the envelope's TO field.
+    #
+    # +HEADER+ _field_ _substring_::
+    #   Matches when _substring_ is in the specified header _field_.
+    #
+    # +BODY+ _string_::
+    #   Matches when _string_ is in the body of the message.
+    #   Does not match on header fields.
+    #
+    #   The server _may_ use flexible matching, rather than simple substring
+    #   matches.  For example, this may use stemming or match only full words.
+    #
+    # +TEXT+ _string_::
+    #   Matches when _string_ is in the header or body of the message.
+    #
+    #   The server _may_ use flexible matching, rather than simple substring
+    #   matches.  For example, this may use stemming or match only full words.
+    #
+    # +BEFORE+ _date_::
+    # +ON+ _date_::
+    # +SINCE+ _date_::
+    #   Matches when the +INTERNALDATE+ is earlier than, on, or later than
+    #   _date_.
+    #
+    # +SENTBEFORE+ _date_::
+    # +SENTON+ _date_::
+    # +SENTSINCE+ _date_::
+    #   Matches when the +Date+ header is earlier than, on, or later than _date_.
+    #
+    # +SMALLER+ _bytes_::
+    # +LARGER+ _bytes_::
+    #   Matches when +RFC822.SIZE+ is smaller/larger than _bytes_.
+    #
+    # ====== Removed from +IMAP4rev2+
+    #
+    # The <tt>\\Recent</tt> flag has been removed from +IMAP4rev2+.  So these
+    # search keys require the +IMAP4rev1+ capability.
     #
-    # <message set>:: a set of message sequence numbers.  "<tt>,</tt>" indicates
-    #                 an interval, "+:+" indicates a range.  For instance,
-    #                 "<tt>2,10:12,15</tt>" means "<tt>2,10,11,12,15</tt>".
+    # +RECENT+::
+    # +UNRECENT+::
+    #   Matches messages with or without the <tt>\\Recent</tt> flag.
     #
-    # BEFORE <date>:: messages with an internal date strictly before
-    #                 <b><date></b>.  The date argument has a format similar
-    #                 to <tt>8-Aug-2002</tt>, and can be formatted using
-    #                 Net::IMAP.format_date.
+    # +NEW+::
+    #   Equivalent to <tt>(RECENT UNSEEN)</tt>.
     #
-    # BODY <string>:: messages that contain <string> within their body.
+    # ====== Extension search keys
     #
-    # CC <string>:: messages containing <string> in their CC field.
+    # The search keys described below are defined by standard \IMAP extensions.
     #
-    # FROM <string>:: messages that contain <string> in their FROM field.
+    # +OLDER+ _interval_::
+    # +YOUNGER+ _interval_::
+    #   Matches when +INTERNALDATE+ is more/less than _interval_ seconds ago.
     #
-    # NEW:: messages with the \Recent, but not the \Seen, flag set.
+    #   <em>Requires the +WITHIN+ capability</em>.
+    #   {[RFC5032]}[https://www.rfc-editor.org/rfc/rfc5032.html]
     #
-    # NOT <search-key>:: negate the following search key.
+    # +ANNOTATION+ _entry_ _attr_ _value_::
+    #   Matches messages that have annotations with entries matching _entry_,
+    #   attributes matching _attr_, and _value_ in the attribute's values.
     #
-    # OR <search-key> <search-key>:: "or" two search keys together.
+    #   <em>Requires the +ANNOTATE-EXPERIMENT-1+ capability</em>.
+    #   {[RFC5257]}[https://www.rfc-editor.org/rfc/rfc5257.html].
     #
-    # ON <date>:: messages with an internal date exactly equal to <date>,
-    #             which has a format similar to 8-Aug-2002.
+    # +FILTER+ _filter_::
+    #   References a _filter_ that is stored on the server and matches all
+    #   messages which would be matched by that filter's search criteria.
     #
-    # SINCE <date>:: messages with an internal date on or after <date>.
+    #   <em>Requires the +FILTERS+ capability</em>.
+    #   {[RFC5466]}[https://www.rfc-editor.org/rfc/rfc5466.html#section-3.1]
     #
-    # SUBJECT <string>:: messages with <string> in their subject.
+    # +FUZZY+ _search-key_::
+    #   Uses fuzzy matching for the specified search key.
     #
-    # TO <string>:: messages with <string> in their TO field.
+    #   <em>Requires the <tt>SEARCH=FUZZY</tt> capability.</em>
+    #   {[RFC6203]}[https://www.rfc-editor.org/rfc/rfc6203.html#section-6].
     #
-    # ===== For example:
+    # +MODSEQ+ _modseq_::
+    #   Matches when +MODSEQ+ is greater than or equal to _modseq_.
     #
-    #   p imap.search(["SUBJECT", "hello", "NOT", "NEW"])
-    #   #=> [1, 6, 7, 8]
+    #   <em>Requires the +CONDSTORE+ capability</em>.
+    #   {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.5].
+    #
+    # +MODSEQ+ _entry_ _entry-type_ _modseq_::
+    #   Matches when a specific metadata _entry_ has been updated since
+    #   _modseq_.
+    #
+    #   For flags, the corresponding _entry_ name is
+    #   <tt>"/flags/#{flag_name}"</tt>, where _flag_name_ includes the
+    #   <tt>\\</tt> prefix.  _entry-type_ can be one of <tt>"shared"</tt>,
+    #   <tt>"priv"</tt> (private), or <tt>"all"</tt>.
+    #
+    #   <em>Requires the +CONDSTORE+ capability</em>.
+    #   {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.5].
+    #
+    # +EMAILID+ _objectid_::
+    # +THREADID+ _objectid_::
+    #   Matches when +EMAILID+/+THREADID+ is equal to _objectid_
+    #   (substring matches are not supported).
+    #
+    #   <em>Requires the +OBJECTID+ capability</em>.
+    #   {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-6]
+    #
+    # +SAVEDATESUPPORTED+::
+    #   Matches every message in the mailbox when the mailbox supports the save
+    #   date attribute.  Otherwise, it matches no messages.
+    #
+    #   <em>Requires the +SAVEDATE+ capability</em>.
+    #   {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3]
+    #
+    # +SAVEDBEFORE+ _date_::
+    # +SAVEDON+ _date_::
+    # +SAVEDSINCE+ _date_::
+    #   Matches when the save date is earlier than, on, or later than _date_.
+    #
+    #   <em>Requires the +SAVEDATE+ capability.</em>
+    #   {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3]
     #
     # ===== Capabilities
     #
-    # If [CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html]] is supported
+    # If CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html] is supported
     # and enabled for the selected mailbox, a non-empty SearchResult will
     # include a +MODSEQ+ value.
     #   imap.select("mbox", condstore: true)
-    #   result = imap.search(["SUBJECT", "hi there", "not", "new")
+    #   result = imap.search(["SUBJECT", "hi there", "not", "new"])
     #   #=> Net::IMAP::SearchResult[1, 6, 7, 8, modseq: 5594]
     #   result.modseq # => 5594
-    def search(keys, charset = nil)
-      return search_internal("SEARCH", keys, charset)
+    def search(...)
+      search_internal("SEARCH", ...)
     end
 
+    # :call-seq:
+    #   uid_search(criteria, charset = nil) -> result
+    #
     # Sends a {UID SEARCH command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
     # to search the mailbox for messages that match the given searching
     # criteria, and returns unique identifiers (<tt>UID</tt>s).
@@ -1997,9 +2200,9 @@ module Net
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
     #
-    # See #search for documentation of search criteria.
-    def uid_search(keys, charset = nil)
-      return search_internal("UID SEARCH", keys, charset)
+    # See #search for documentation of parameters.
+    def uid_search(...)
+      search_internal("UID SEARCH", ...)
     end
 
     # :call-seq:
@@ -2397,11 +2600,17 @@ module Net
     # checks the connection for each 60 seconds.
     #
     #   loop do
-    #     imap.idle(60) do |res|
-    #       ...
+    #     imap.idle(60) do |response|
+    #       do_something_with(response)
+    #       imap.idle_done if some_condition?(response)
     #     end
     #   end
     #
+    # Returns the server's response to indicate the IDLE state has ended.
+    # Returns +nil+ if the server does not respond to #idle_done within
+    # {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]
+    # seconds.
+    #
     # Related: #idle_done, #noop, #check
     #
     # ===== Capabilities
@@ -2429,7 +2638,7 @@ module Net
           unless @receiver_thread_terminating
             remove_response_handler(response_handler)
             put_string("DONE#{CRLF}")
-            response = get_tagged_response(tag, "IDLE", @idle_response_timeout)
+            response = get_tagged_response(tag, "IDLE", idle_response_timeout)
           end
         end
       end
@@ -2437,7 +2646,11 @@ module Net
       return response
     end
 
-    # Leaves IDLE.
+    # Leaves IDLE, allowing #idle to return.
+    #
+    # If the server does not respond within
+    # {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]
+    # seconds, #idle will return +nil+.
     #
     # Related: #idle
     def idle_done
@@ -2449,40 +2662,98 @@ module Net
       end
     end
 
+    RESPONSES_DEPRECATION_MSG =
+      "Pass a type or block to #responses, " \
+      "set config.responses_without_block to :frozen_dup " \
+      "or :silence_deprecation_warning, " \
+      "or use #extract_responses or #clear_responses."
+    private_constant :RESPONSES_DEPRECATION_MSG
+
     # :call-seq:
+    #   responses       -> hash of {String => Array} (see config.responses_without_block)
+    #   responses(type) -> frozen array
     #   responses       {|hash|  ...} -> block result
     #   responses(type) {|array| ...} -> block result
     #
-    # Yields unhandled responses and returns the result of the block.
+    # Yields or returns unhandled server responses.  Unhandled responses are
+    # stored in a hash, with arrays of UntaggedResponse#data keyed by
+    # UntaggedResponse#name and <em>non-+nil+</em> untagged ResponseCode#data
+    # keyed by ResponseCode#name.
+    #
+    # When a block is given, yields unhandled responses and returns the block's
+    # result.  Without a block, returns the unhandled responses.
+    #
+    # [With +type+]
+    #   Yield or return only the array of responses for that +type+.
+    #   When no block is given, the returned array is a frozen copy.
+    # [Without +type+]
+    #   Yield or return the entire responses hash.
+    #
+    #   When no block is given, the behavior is determined by
+    #   Config#responses_without_block:
+    #   >>>
+    #     [+:silence_deprecation_warning+ <em>(original behavior)</em>]
+    #       Returns the mutable responses hash (without any warnings).
+    #       <em>This is not thread-safe.</em>
+    #
+    #     [+:warn+ <em>(default since +v0.5+)</em>]
+    #       Prints a warning and returns the mutable responses hash.
+    #       <em>This is not thread-safe.</em>
     #
-    # Unhandled responses are stored in a hash, with arrays of
-    # <em>non-+nil+</em> UntaggedResponse#data keyed by UntaggedResponse#name
-    # and ResponseCode#data keyed by ResponseCode#name.  Call without +type+ to
-    # yield the entire responses hash.  Call with +type+ to yield only the array
-    # of responses for that type.
+    #     [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
+    #       Returns a frozen copy of the unhandled responses hash, with frozen
+    #       array values.
+    #
+    #     [+:raise+]
+    #       Raise an +ArgumentError+ with the deprecation warning.
     #
     # For example:
     #
     #   imap.select("inbox")
-    #   p imap.responses("EXISTS", &:last)
+    #   p imap.responses("EXISTS").last
     #   #=> 2
+    #   p imap.responses("UIDNEXT", &:last)
+    #   #=> 123456
     #   p imap.responses("UIDVALIDITY", &:last)
     #   #=> 968263756
+    #   p imap.responses {|responses|
+    #     {
+    #       exists:      responses.delete("EXISTS").last,
+    #       uidnext:     responses.delete("UIDNEXT").last,
+    #       uidvalidity: responses.delete("UIDVALIDITY").last,
+    #     }
+    #   }
+    #   #=> {:exists=>2, :uidnext=>123456, :uidvalidity=>968263756}
+    #   # "EXISTS", "UIDNEXT", and "UIDVALIDITY" have been removed:
+    #   p imap.responses(&:keys)
+    #   #=> ["FLAGS", "OK", "PERMANENTFLAGS", "RECENT", "HIGHESTMODSEQ"]
+    #
+    # Related: #extract_responses, #clear_responses, #response_handlers, #greeting
     #
+    # ===== Thread safety
     # >>>
     #   *Note:* Access to the responses hash is synchronized for thread-safety.
     #   The receiver thread and response_handlers cannot process new responses
     #   until the block completes.  Accessing either the response hash or its
-    #   response type arrays outside of the block is unsafe.
+    #   response type arrays outside of the block is unsafe.  They can be safely
+    #   updated inside the block.  Consider using #clear_responses or
+    #   #extract_responses instead.
     #
-    #   Calling without a block is unsafe and deprecated.  Future releases will
-    #   raise ArgumentError unless a block is given.
+    #   Net::IMAP will add and remove responses from the responses hash and its
+    #   array values, in the calling threads for commands and in the receiver
+    #   thread, but will not modify any responses after adding them to the
+    #   responses hash.
+    #
+    # ===== Clearing responses
     #
     # Previously unhandled responses are automatically cleared before entering a
     # mailbox with #select or #examine.  Long-lived connections can receive many
     # unhandled server responses, which must be pruned or they will continually
     # consume more memory.  Update or clear the responses hash or arrays inside
-    # the block, or use #clear_responses.
+    # the block, or remove responses with #extract_responses, #clear_responses,
+    # or #add_response_handler.
+    #
+    # ===== Missing responses
     #
     # Only non-+nil+ data is stored.  Many important response codes have no data
     # of their own, but are used as "tags" on the ResponseText object they are
@@ -2493,15 +2764,25 @@ module Net
     # ResponseCode#data on tagged responses.  Although some command methods do
     # return the TaggedResponse directly, #add_response_handler must be used to
     # handle all response codes.
-    #
-    # Related: #clear_responses, #response_handlers, #greeting
     def responses(type = nil)
       if block_given?
         synchronize { yield(type ? @responses[type.to_s.upcase] : @responses) }
       elsif type
-        raise ArgumentError, "Pass a block or use #clear_responses"
+        synchronize { @responses[type.to_s.upcase].dup.freeze }
       else
-        # warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+        case config.responses_without_block
+        when :raise
+          raise ArgumentError, RESPONSES_DEPRECATION_MSG
+        when :warn
+          warn(RESPONSES_DEPRECATION_MSG, uplevel: 1, category: :deprecated)
+        when :frozen_dup
+          synchronize {
+            responses = @responses.transform_values(&:freeze)
+            responses.default_proc = nil
+            responses.default = [].freeze
+            return responses.freeze
+          }
+        end
         @responses
       end
     end
@@ -2516,7 +2797,7 @@ module Net
     # Clearing responses is synchronized with other threads.  The lock is
     # released before returning.
     #
-    # Related: #responses, #response_handlers
+    # Related: #extract_responses, #responses, #response_handlers
     def clear_responses(type = nil)
       synchronize {
         if type
@@ -2530,6 +2811,30 @@ module Net
         .freeze
     end
 
+    # :call-seq:
+    #   extract_responses(type) {|response| ... } -> array
+    #
+    # Yields all of the unhandled #responses for a single response +type+.
+    # Removes and returns the responses for which the block returns a true
+    # value.
+    #
+    # Extracting responses is synchronized with other threads.  The lock is
+    # released before returning.
+    #
+    # Related: #responses, #clear_responses
+    def extract_responses(type)
+      type = String.try_convert(type) or
+        raise ArgumentError, "type must be a string"
+      raise ArgumentError, "must provide a block" unless block_given?
+      extracted = []
+      responses(type) do |all|
+        all.reject! do |response|
+          extracted << response if yield response
+        end
+      end
+      extracted
+    end
+
     # Returns all response handlers, including those that are added internally
     # by commands.  Each response handler will be called with every new
     # UntaggedResponse, TaggedResponse, and ContinuationRequest.
@@ -2582,8 +2887,6 @@ module Net
     PORT = 143         # :nodoc:
     SSL_PORT = 993   # :nodoc:
 
-    @@debug = false
-
     def start_imap_connection
       @greeting        = get_server_greeting
       @capabilities    = capabilities_from_resp_code @greeting
@@ -2611,12 +2914,12 @@ module Net
     end
 
     def tcp_socket(host, port)
-      s = Socket.tcp(host, port, :connect_timeout => @open_timeout)
+      s = Socket.tcp(host, port, :connect_timeout => open_timeout)
       s.setsockopt(:SOL_SOCKET, :SO_KEEPALIVE, true)
       s
     rescue Errno::ETIMEDOUT
       raise Net::OpenTimeout, "Timeout to open TCP connection to " +
-        "#{host}:#{port} (exceeds #{@open_timeout} seconds)"
+        "#{host}:#{port} (exceeds #{open_timeout} seconds)"
     end
 
     def receive_responses
@@ -2728,7 +3031,7 @@ module Net
         end
       end
       return nil if buff.length == 0
-      if @@debug
+      if config.debug?
         $stderr.print(buff.gsub(/^/n, "S: "))
       end
       return @parser.parse(buff)
@@ -2807,7 +3110,7 @@ module Net
 
     def put_string(str)
       @sock.print(str)
-      if @@debug
+      if config.debug?
         if @debug_output_bol
           $stderr.print("C: ")
         end
@@ -2820,18 +3123,19 @@ module Net
       end
     end
 
-    def search_internal(cmd, keys, charset)
-      if keys.instance_of?(String)
-        keys = [RawData.new(keys)]
+    def enforce_logindisabled?
+      if config.enforce_logindisabled == :when_capabilities_cached
+        capabilities_cached?
       else
-        normalize_searching_criteria(keys)
+        config.enforce_logindisabled
       end
+    end
+
+    def search_internal(cmd, keys, charset = nil)
+      keys = normalize_searching_criteria(keys)
+      args = charset ? ["CHARSET", charset, *keys] : keys
       synchronize do
-        if charset
-          send_command(cmd, "CHARSET", charset, *keys)
-        else
-          send_command(cmd, *keys)
-        end
+        send_command(cmd, *args)
         clear_responses("SEARCH").last || []
       end
     end
@@ -2853,9 +3157,9 @@ module Net
       synchronize do
         clear_responses("FETCH")
         if mod
-          send_command(cmd, MessageSet.new(set), attr, mod)
+          send_command(cmd, SequenceSet.new(set), attr, mod)
         else
-          send_command(cmd, MessageSet.new(set), attr)
+          send_command(cmd, SequenceSet.new(set), attr)
         end
         clear_responses("FETCH")
       end
@@ -2863,7 +3167,7 @@ module Net
 
     def store_internal(cmd, set, attr, flags, unchangedsince: nil)
       attr = RawData.new(attr) if attr.instance_of?(String)
-      args = [MessageSet.new(set)]
+      args = [SequenceSet.new(set)]
       args << ["UNCHANGEDSINCE", Integer(unchangedsince)] if unchangedsince
       args << attr << flags
       synchronize do
@@ -2874,15 +3178,11 @@ module Net
     end
 
     def copy_internal(cmd, set, mailbox)
-      send_command(cmd, MessageSet.new(set), mailbox)
+      send_command(cmd, SequenceSet.new(set), mailbox)
     end
 
     def sort_internal(cmd, sort_keys, search_keys, charset)
-      if search_keys.instance_of?(String)
-        search_keys = [RawData.new(search_keys)]
-      else
-        normalize_searching_criteria(search_keys)
-      end
+      search_keys = normalize_searching_criteria(search_keys)
       synchronize do
         send_command(cmd, sort_keys, charset, *search_keys)
         clear_responses("SORT").last || []
@@ -2890,25 +3190,39 @@ module Net
     end
 
     def thread_internal(cmd, algorithm, search_keys, charset)
-      if search_keys.instance_of?(String)
-        search_keys = [RawData.new(search_keys)]
-      else
-        normalize_searching_criteria(search_keys)
-      end
+      search_keys = normalize_searching_criteria(search_keys)
       synchronize do
         send_command(cmd, algorithm, charset, *search_keys)
         clear_responses("THREAD").last || []
       end
     end
 
-    def normalize_searching_criteria(keys)
-      keys.collect! do |i|
-        case i
-        when -1, Range, Array
-          MessageSet.new(i)
+    def normalize_searching_criteria(criteria)
+      return RawData.new(criteria) if criteria.is_a?(String)
+      criteria.map {|i|
+        if coerce_search_arg_to_seqset?(i)
+          SequenceSet[i]
         else
           i
         end
+      }
+    end
+
+    def coerce_search_arg_to_seqset?(obj)
+      case obj
+      when Set, -1, :* then true
+      when Range       then true
+      when Array       then obj.all? { coerce_search_array_arg_to_seqset? _1 }
+      else                  obj.respond_to?(:to_sequence_set)
+      end
+    end
+
+    def coerce_search_array_arg_to_seqset?(obj)
+      case obj
+      when Integer then obj.positive? || obj == -1
+      when String  then ResponseParser::Patterns::SEQUENCE_SET_STR.match?(obj.b)
+      else
+        coerce_search_arg_to_seqset?(obj)
       end
     end
 
@@ -2934,7 +3248,7 @@ module Net
       @sock = SSLSocket.new(@sock, ssl_ctx)
       @sock.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
-      ssl_socket_connect(@sock, @open_timeout)
+      ssl_socket_connect(@sock, open_timeout)
       if ssl_ctx.verify_mode != VERIFY_NONE
         @sock.post_connection_check(@host)
         @tls_verified = true
@@ -2959,6 +3273,7 @@ module Net
 end
 
 require_relative "imap/errors"
+require_relative "imap/config"
 require_relative "imap/command_data"
 require_relative "imap/data_encoding"
 require_relative "imap/flags"