net-imap 0.4.17 → 0.5.2

data/lib/net/imap.rb

@@ -414,7 +414,7 @@ module Net
   # >>>
   #   <em>The following are folded into +IMAP4rev2+ but are currently
   #   unsupported or incompletely supported by</em> Net::IMAP<em>: RFC4466
-  #   extensions, +ESEARCH+, +SEARCHRES+, +LIST-EXTENDED+, +LIST-STATUS+,
+  #   extensions, +SEARCHRES+, +LIST-EXTENDED+, +LIST-STATUS+,
   #   +LITERAL-+, and +SPECIAL-USE+.</em>
   #
   # ==== RFC2087: +QUOTA+
@@ -466,6 +466,10 @@ module Net
   # - Updates #append with the +APPENDUID+ ResponseCode
   # - Updates #copy, #move with the +COPYUID+ ResponseCode
   #
+  # ==== RFC4731: +ESEARCH+
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
+  # - Updates #search, #uid_search with +return+ options and ESearchResult.
+  #
   # ==== RFC4959: +SASL-IR+
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
   # - Updates #authenticate with the option to send an initial response.
@@ -719,7 +723,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.17"
+    VERSION = "0.5.2"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -946,9 +950,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
@@ -956,11 +957,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!
@@ -1131,7 +1127,7 @@ module Net
     #
     # See [ID[https://tools.ietf.org/html/rfc2971]] for field definitions.
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +ID+
     # [RFC2971[https://tools.ietf.org/html/rfc2971]].
@@ -1213,7 +1209,7 @@ module Net
     #
     # Related: Net::IMAP.new, #login, #authenticate
     #
-    # ===== Capability
+    # ==== Capability
     # Clients should not call #starttls unless the server advertises the
     # +STARTTLS+ capability.
     #
@@ -1244,6 +1240,9 @@ module Net
     # +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
     # mechanism must be consulted for its specific parameters.</em>
@@ -1338,29 +1337,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: config.sasl_ir,
-                     **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]
@@ -1377,16 +1356,12 @@ module Net
     #
     # Related: #authenticate, #starttls
     #
-    # ===== Capabilities
+    # ==== 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.
@@ -1394,6 +1369,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
@@ -1419,7 +1397,7 @@ module Net
     #
     # Related: #examine
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # If [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]] is supported,
     # the server may return an untagged "NO" response with a "UIDNOTSTICKY"
@@ -1537,7 +1515,7 @@ module Net
     #
     # Related: #lsub, MailboxList
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   imap.create("foo/bar")
     #   imap.create("foo/baz")
@@ -1588,7 +1566,7 @@ module Net
     #
     # Related: #list, Namespaces, Namespace
     #
-    # ===== For example:
+    # ==== For example:
     #
     #    if capable?("NAMESPACE")
     #      namespaces = imap.namespace
@@ -1602,7 +1580,7 @@ module Net
     #      end
     #    end
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +NAMESPACE+
     # [RFC2342[https://tools.ietf.org/html/rfc2342]].
@@ -1641,7 +1619,7 @@ module Net
     #
     # Related: #list, MailboxList
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +XLIST+,
     # a deprecated Gmail extension (replaced by +SPECIAL-USE+).
@@ -1664,7 +1642,7 @@ module Net
     #
     # Related: #getquota, #setquota, MailboxQuotaRoot, MailboxQuota
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +QUOTA+
     # [RFC2087[https://tools.ietf.org/html/rfc2087]].
@@ -1685,7 +1663,7 @@ module Net
     #
     # Related: #getquotaroot, #setquota, MailboxQuota
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +QUOTA+
     # [RFC2087[https://tools.ietf.org/html/rfc2087]].
@@ -1703,7 +1681,7 @@ module Net
     #
     # Related: #getquota, #getquotaroot
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +QUOTA+
     # [RFC2087[https://tools.ietf.org/html/rfc2087]].
@@ -1723,7 +1701,7 @@ module Net
     #
     # Related: #getacl
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +ACL+
     # [RFC4314[https://tools.ietf.org/html/rfc4314]].
@@ -1741,7 +1719,7 @@ module Net
     #
     # Related: #setacl, MailboxACLItem
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +ACL+
     # [RFC4314[https://tools.ietf.org/html/rfc4314]].
@@ -1778,7 +1756,7 @@ module Net
     # for +mailbox+ cannot be returned; for instance, because it
     # does not exist.
     #
-    # ===== Supported attributes
+    # ==== Supported attributes
     #
     # +MESSAGES+::    The number of messages in the mailbox.
     #
@@ -1809,12 +1787,12 @@ module Net
     # Unsupported attributes may be requested.  The attribute value will be
     # either an Integer or an ExtensionData object.
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   p imap.status("inbox", ["MESSAGES", "RECENT"])
     #   #=> {"RECENT"=>0, "MESSAGES"=>44}
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # +SIZE+ requires the server's capabilities to include either +IMAP4rev2+ or
     # <tt>STATUS=SIZE</tt>
@@ -1854,7 +1832,7 @@ module Net
     # not exist (it is not created automatically), or if the flags,
     # date_time, or message arguments contain errors.
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
     # supported and the destination supports persistent UIDs, the server's
@@ -1903,7 +1881,7 @@ module Net
     #
     # Related: #close
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +UNSELECT+
     # [RFC3691[https://tools.ietf.org/html/rfc3691]].
@@ -1944,88 +1922,406 @@ module Net
     #
     # Related: #expunge
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +UIDPLUS+
     # [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
+    #   search(criteria, charset: nil, return: nil) -> result
     #
-    # Returns a SearchResult object.  SearchResult inherits from Array (for
-    # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
-    # capability has been enabled.
+    # 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 either a SearchResult or an ESearchResult.  SearchResult
+    # inherits from Array (for backward compatibility) but adds
+    # SearchResult#modseq when the +CONDSTORE+ capability has been enabled.
+    # ESearchResult also implements to_a{rdoc-ref:ESearchResult#to_a}, for
+    # compatibility with SearchResult.
+    #
+    # +criteria+ is one or more search keys and their arguments, which may be
+    # provided as an array or a string.
+    # See {"Argument translation"}[rdoc-ref:#search@Argument+translation]
+    # and {"Search criteria"}[rdoc-ref:#search@Search+criteria], below.
+    #
+    # +return+ options control what kind of information is returned about
+    # messages matching the search +criteria+.  Specifying +return+ should force
+    # the server to return an ESearchResult instead of a SearchResult, but some
+    # servers disobey this requirement.  <em>Requires an extended search
+    # capability, such as +ESEARCH+ or +IMAP4rev2+.</em>
+    # See {"Argument translation"}[rdoc-ref:#search@Argument+translation]
+    # and {"Return options"}[rdoc-ref:#search@Return+options], below.
+    #
+    # +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.
+    #
+    # _NOTE:_ Return options and charset may be sent as part of +criteria+.  Do
+    # not use the +return+ or +charset+ arguments when either return options or
+    # charset are embedded in +criteria+.
     #
     # Related: #uid_search
     #
-    # ===== Search criteria
+    # ==== For example:
+    #
+    #   imap.search(["SUBJECT", "hello", "NOT", "SEEN"])
+    #   #=> [1, 6, 7, 8]
     #
-    # For a full list of search criteria,
+    # The following assumes the server supports +ESEARCH+ and +CONDSTORE+:
+    #
+    #   result = imap.uid_search(["UID", 12345.., "MODSEQ", 620_162_338],
+    #                            return: %w(all count min max))
+    #   # => #<data Net::IMAP::ESearchResult tag="RUBY0123", uid=true,
+    #   #       data=[["ALL", Net::IMAP::SequenceSet["12346:12349,22222:22230"]],
+    #   #             ["COUNT", 13], ["MIN", 12346], ["MAX", 22230],
+    #   #             ["MODSEQ", 917162488]]>
+    #   result.to_a   # => [12346, 12347, 12348, 12349, 22222, 22223, 22224,
+    #                 #     22225, 22226, 22227, 22228, 22229, 22230]
+    #   result.uid?   # => true
+    #   result.count  # => 13
+    #   result.min    # => 12346
+    #   result.max    # => 22230
+    #   result.modseq # => 917162488
+    #
+    # Using +return+ options to limit the result to only min, max, and count:
+    #
+    #   result = imap.uid_search(["UID", 12345..,], return: %w(count min max))
+    #   # => #<data Net::IMAP::ESearchResult tag="RUBY0124", uid=true,
+    #   #       data=[["COUNT", 13], ["MIN", 12346], ["MAX", 22230]]>
+    #   result.to_a   # => []
+    #   result.count  # => 13
+    #   result.min    # => 12346
+    #   result.max    # => 22230
+    #
+    # Return options and charset may be sent as keyword args or embedded in the
+    # +criteria+ arg, but they must be in the correct order: <tt>"RETURN (...)
+    # CHARSET ... criteria..."</tt>.  The following searches
+    # send the exact same command to the server:
+    #
+    #    # Return options and charset as keyword arguments (preferred)
+    #    imap.search(%w(OR UNSEEN FLAGGED), return: %w(MIN MAX), charset: "UTF-8")
+    #    # Embedding return and charset in the criteria array
+    #    imap.search(["RETURN", %w(MIN MAX), "CHARSET", "UTF-8", *%w(OR UNSEEN FLAGGED)])
+    #    # Embedding return and charset in the criteria string
+    #    imap.search("RETURN (MIN MAX) CHARSET UTF-8 OR UNSEEN FLAGGED")
+    #
+    # Sending charset as the second positional argument is supported for
+    # backward compatibility.  Future versions may print a deprecation warning:
+    #    imap.search(%w(OR UNSEEN FLAGGED), "UTF-8", return: %w(MIN MAX))
+    #
+    # ==== Argument translation
+    #
+    # [+return+ options]
+    #   Must be an Array.  Return option names may be either strings or symbols.
+    #   +Range+ elements which begin and end with negative integers are encoded
+    #   for use with +PARTIAL+--any other ranges are converted to SequenceSet.
+    #   Unlike +criteria+, other return option arguments are not automatically
+    #   converted to SequenceSet.
+    #
+    # [When +criteria+ is an Array]
+    #   When the array begins with <tt>"RETURN"</tt> (case insensitive), the
+    #   second array element is translated like the +return+ parameter (as
+    #   described above).
+    #
+    #   Every other member is a +SEARCH+ command argument:
+    #   [SequenceSet]
+    #     Encoded as an \IMAP +sequence-set+ with SequenceSet#valid_string.
+    #   [Set, Range, <tt>-1</tt>, +:*+, responds to +#to_sequence_set+]
+    #     Converted to SequenceSet for validation and encoding.
+    #   [nested sequence-set +Array+]
+    #     When every element in a nested array is one of the above types, a
+    #     positive +Integer+, a sequence-set formatted +String+, or a deeply
+    #     nested +Array+ of these same types, the array will be converted to
+    #     SequenceSet for validation and encoding.
+    #   [Any other nested +Array+]
+    #     Otherwise, a nested array is encoded as a parenthesized list, to
+    #     combine multiple search keys (e.g., for use with +OR+ and +NOT+).
+    #   [+String+]
+    #     Sent verbatim when it is a valid \IMAP +atom+, and encoded as an \IMAP
+    #     +quoted+ or +literal+ string otherwise.  Every standard search key
+    #     name is a valid \IMAP +atom+ and every standard search key string
+    #     argument is an +astring+ which may be encoded as +atom+, +quoted+, or
+    #     +literal+.
+    #
+    #     *Note:* <tt>*</tt> is not a valid \IMAP +atom+ character.  Any string
+    #     containing <tt>*</tt> will be encoded as a +quoted+ string, _not_ a
+    #     +sequence-set+.
+    #   [+Integer+ (except for <tt>-1</tt>)]
+    #     Encoded using +#to_s+.
+    #   [+Date+]
+    #     Encoded as an \IMAP date (see ::encode_date).
+    #
+    # [When +criteria+ is a String]
+    #   +criteria+ will be sent directly to the server <em>without any
+    #   validation or encoding</em>.
+    #
+    #   <em>*WARNING:* This is vulnerable to injection attacks when external
+    #   inputs are used.</em>
+    #
+    # ==== Return options
+    #
+    # For full definitions of the standard return options and return data, see
+    # the relevant RFCs.
+    #
+    # ===== +ESEARCH+ or +IMAP4rev2+
+    #
+    # The following return options require either +ESEARCH+ or +IMAP4rev2+.
+    # See [{RFC4731 §3.1}[https://rfc-editor.org/rfc/rfc4731#section-3.1]] or
+    # [{IMAP4rev2 §6.4.4}[https://www.rfc-editor.org/rfc/rfc9051.html#section-6.4.4]].
+    #
+    # [+ALL+]
+    #    Returns ESearchResult#all with a SequenceSet of all matching sequence
+    #    numbers or UIDs.  This is the default, when return options are empty.
+    #
+    #    For compatibility with SearchResult, ESearchResult#to_a returns an
+    #    Array of message sequence numbers or UIDs.
+    # [+COUNT+]
+    #    Returns ESearchResult#count with the number of matching messages.
+    # [+MAX+]
+    #    Returns ESearchResult#max with the highest matching sequence number or
+    #    UID.
+    # [+MIN+]
+    #    Returns ESearchResult#min with the lowest matching sequence number or
+    #    UID.
+    #
+    # ===== +CONDSTORE+
+    #
+    # ESearchResult#modseq return data does not have a corresponding return
+    # option.  Instead, it is returned if the +MODSEQ+ search key is used or
+    # when the +CONDSTORE+ extension is enabled for the selected mailbox.
+    # See [{RFC4731 §3.2}[https://www.rfc-editor.org/rfc/rfc4731#section-3.2]]
+    # or [{RFC7162 §2.1.5}[https://www.rfc-editor.org/rfc/rfc7162#section-3.1.5]].
+    #
+    # ===== +RFC4466+ compatible extensions
+    #
+    # {RFC4466 §2.6}[https://www.rfc-editor.org/rfc/rfc4466.html#section-2.6]
+    # defines standard syntax for search extensions.  Net::IMAP allows sending
+    # unknown search return options and will parse unknown search extensions'
+    # return values into ExtensionData.  Please note that this is an
+    # intentionally _unstable_ API.  Future releases may return different
+    # (incompatible) objects, <em>without deprecation or warning</em>.
+    #
+    # ==== 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+.
     #
-    # <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>".
+    # 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.
     #
-    # 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.
+    # ===== Search keys that match all messages
     #
-    # BODY <string>:: messages that contain <string> within their body.
+    # [+ALL+]
+    #   The default initial key.  Matches every message in the mailbox.
     #
-    # CC <string>:: messages containing <string> in their CC field.
+    # [+SAVEDATESUPPORTED+]
+    #   Matches every message in the mailbox when the mailbox supports the save
+    #   date attribute.  Otherwise, it matches no messages.
     #
-    # FROM <string>:: messages that contain <string> in their FROM field.
+    #   <em>Requires +SAVEDATE+ capability</em>.
+    #   {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3]
     #
-    # NEW:: messages with the \Recent, but not the \Seen, flag set.
+    # ===== Sequence set search keys
     #
-    # NOT <search-key>:: negate the following search key.
+    # [_sequence-set_]
+    #   Matches messages with message sequence numbers in _sequence-set_.
     #
-    # OR <search-key> <search-key>:: "or" two search keys together.
+    #   _Note:_ this search key has no label.
     #
-    # ON <date>:: messages with an internal date exactly equal to <date>,
-    #             which has a format similar to 8-Aug-2002.
+    #   <em>+UIDONLY+ must *not* be enabled.</em>
+    #   {[RFC9586]}[https://www.rfc-editor.org/rfc/rfc9586.html]
     #
-    # SINCE <date>:: messages with an internal date on or after <date>.
+    # [+UID+ _sequence-set_]
+    #   Matches messages with a UID in _sequence-set_.
     #
-    # SUBJECT <string>:: messages with <string> in their subject.
+    # ===== Compound search keys
     #
-    # TO <string>:: messages with <string> in their TO field.
+    # [(_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.
     #
-    # ===== For example:
+    #   _Note:_ this search key has no label.
     #
-    #   p imap.search(["SUBJECT", "hello", "NOT", "NEW"])
-    #   #=> [1, 6, 7, 8]
+    # [+OR+ _search-key_ _search-key_]
+    #   Matches messages which match either _search-key_ argument.
+    #
+    # [+NOT+ _search-key_]
+    #   Matches messages which do not match _search-key_.
+    #
+    # [+FUZZY+ _search-key_]
+    #   Uses fuzzy matching for the specified search key.
+    #
+    #   <em>Requires <tt>SEARCH=FUZZY</tt> capability.</em>
+    #   {[RFC6203]}[https://www.rfc-editor.org/rfc/rfc6203.html#section-6].
+    #
+    # ===== Flags search keys
+    #
+    # [+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_.
+    #
+    # [+RECENT+, +UNRECENT+]
+    #   Matches messages with or without the <tt>\\Recent</tt> flag.
+    #
+    #   *NOTE:* The <tt>\\Recent</tt> flag has been removed from +IMAP4rev2+.
+    # [+NEW+]
+    #   Equivalent to <tt>(RECENT UNSEEN)</tt>.
+    #
+    #   *NOTE:* The <tt>\\Recent</tt> flag has been removed from +IMAP4rev2+.
+    #
+    # ===== Header field substring search keys
+    #
+    # [+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 text search keys
+    # [+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.
+    #
+    # ===== Date/Time search keys
+    #
+    # [+SENTBEFORE+ _date_]
+    # [+SENTON+ _date_]
+    # [+SENTSINCE+ _date_]
+    #   Matches when the +Date+ header is earlier than, on, or later than _date_.
+    #
+    # [+BEFORE+ _date_]
+    # [+ON+ _date_]
+    # [+SINCE+ _date_]
+    #   Matches when the +INTERNALDATE+ is earlier than, on, or later than
+    #   _date_.
+    #
+    # [+OLDER+ _interval_]
+    # [+YOUNGER+ _interval_]
+    #   Matches when the +INTERNALDATE+ is more/less than _interval_ seconds ago.
+    #
+    #   <em>Requires +WITHIN+ capability</em>.
+    #   {[RFC5032]}[https://www.rfc-editor.org/rfc/rfc5032.html]
     #
-    # ===== Capabilities
+    # [+SAVEDBEFORE+ _date_]
+    # [+SAVEDON+ _date_]
+    # [+SAVEDSINCE+ _date_]
+    #   Matches when the save date is earlier than, on, or later than _date_.
     #
-    # If [CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html]] is supported
+    #   <em>Requires +SAVEDATE+ capability.</em>
+    #   {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3]
+    #
+    # ===== Other message attribute search keys
+    #
+    # [+SMALLER+ _bytes_]
+    # [+LARGER+ _bytes_]
+    #   Matches when +RFC822.SIZE+ is smaller or larger than _bytes_.
+    #
+    # [+ANNOTATION+ _entry_ _attr_ _value_]
+    #   Matches messages that have annotations with entries matching _entry_,
+    #   attributes matching _attr_, and _value_ in the attribute's values.
+    #
+    #   <em>Requires +ANNOTATE-EXPERIMENT-1+ capability</em>.
+    #   {[RFC5257]}[https://www.rfc-editor.org/rfc/rfc5257.html].
+    #
+    # [+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.
+    #
+    #   <em>Requires +FILTERS+ capability</em>.
+    #   {[RFC5466]}[https://www.rfc-editor.org/rfc/rfc5466.html#section-3.1]
+    #
+    # [+MODSEQ+ _modseq_]
+    #   Matches when +MODSEQ+ is greater than or equal to _modseq_.
+    #
+    #   <em>Requires +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 +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 +OBJECTID+ capability</em>.
+    #   {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-6]
+    #
+    # ==== Capabilities
+    #
+    # Return options should only be specified when the server supports
+    # +IMAP4rev2+ or an extension that allows them, such as +ESEARCH+
+    # [RFC4731[https://rfc-editor.org/rfc/rfc4731#section-3.1]].
+    #
+    # When +IMAP4rev2+ is enabled, or when the server supports +IMAP4rev2+ but
+    # not +IMAP4rev1+, ESearchResult is always returned instead of SearchResult.
+    #
+    # 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
+    #   uid_search(criteria, charset: nil, return: 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).
@@ -2034,9 +2330,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:
@@ -2064,7 +2360,7 @@ module Net
     #
     # Related: #uid_search, FetchData
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   p imap.fetch(6..8, "UID")
     #   #=> [#<Net::IMAP::FetchData seqno=6, attr={"UID"=>98}>, \\
@@ -2082,7 +2378,7 @@ module Net
     #   p data.attr["UID"]
     #   #=> 98
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # Many extensions define new message +attr+ names.  See FetchData for a list
     # of supported extension fields.
@@ -2111,7 +2407,7 @@ module Net
     #
     # Related: #fetch, FetchData
     #
-    # ===== Capabilities
+    # ==== Capabilities
     # Same as #fetch.
     def uid_fetch(set, attr, mod = nil, changedsince: nil)
       fetch_internal("UID FETCH", set, attr, mod, changedsince: changedsince)
@@ -2145,14 +2441,14 @@ module Net
     #
     # Related: #uid_store
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   p imap.store(6..8, "+FLAGS", [:Deleted])
     #   #=> [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS"=>[:Seen, :Deleted]}>,
     #        #<Net::IMAP::FetchData seqno=7, attr={"FLAGS"=>[:Seen, :Deleted]}>,
     #        #<Net::IMAP::FetchData seqno=8, attr={"FLAGS"=>[:Seen, :Deleted]}>]
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # Extensions may define new data items to be used with #store.
     #
@@ -2176,7 +2472,7 @@ module Net
     #
     # Related: #store
     #
-    # ===== Capabilities
+    # ==== Capabilities
     # Same as #store.
     def uid_store(set, attr, flags, unchangedsince: nil)
       store_internal("UID STORE", set, attr, flags, unchangedsince: unchangedsince)
@@ -2189,7 +2485,7 @@ module Net
     #
     # Related: #uid_copy
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
     # supported, the server's response should include a +COPYUID+ response code
@@ -2206,7 +2502,7 @@ module Net
     #
     # Similar to #copy, but +set+ contains unique identifiers.
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # +UIDPLUS+ affects #uid_copy the same way it affects #copy.
     def uid_copy(set, mailbox)
@@ -2221,7 +2517,7 @@ module Net
     #
     # Related: #uid_move
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +MOVE+
     # [RFC6851[https://tools.ietf.org/html/rfc6851]].
@@ -2245,7 +2541,7 @@ module Net
     #
     # Related: #move
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # Same as #move: The server's capabilities must include +MOVE+
     # [RFC6851[https://tools.ietf.org/html/rfc6851]].  +UIDPLUS+ also affects
@@ -2265,14 +2561,14 @@ module Net
     #
     # Related: #uid_sort, #search, #uid_search, #thread, #uid_thread
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   p imap.sort(["FROM"], ["ALL"], "US-ASCII")
     #   #=> [1, 2, 3, 5, 6, 7, 8, 4, 9]
     #   p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")
     #   #=> [6, 7, 8, 1]
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +SORT+
     # [RFC5256[https://tools.ietf.org/html/rfc5256]].
@@ -2287,7 +2583,7 @@ module Net
     #
     # Related: #sort, #search, #uid_search, #thread, #uid_thread
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +SORT+
     # [RFC5256[https://tools.ietf.org/html/rfc5256]].
@@ -2312,7 +2608,7 @@ module Net
     #
     # Related: #uid_thread, #search, #uid_search, #sort, #uid_sort
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +THREAD+
     # [RFC5256[https://tools.ietf.org/html/rfc5256]].
@@ -2326,7 +2622,7 @@ module Net
     #
     # Related: #thread, #search, #uid_search, #sort, #uid_sort
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +THREAD+
     # [RFC5256[https://tools.ietf.org/html/rfc5256]].
@@ -2345,7 +2641,7 @@ module Net
     #
     # Related: #capable?, #capabilities, #capability
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include
     # +ENABLE+ [RFC5161[https://tools.ietf.org/html/rfc5161]]
@@ -2447,7 +2743,7 @@ module Net
     #
     # Related: #idle_done, #noop, #check
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +IDLE+
     # [RFC2177[https://tools.ietf.org/html/rfc2177]].
@@ -2564,7 +2860,7 @@ module Net
     #
     # Related: #extract_responses, #clear_responses, #response_handlers, #greeting
     #
-    # ===== Thread safety
+    # ==== Thread safety
     # >>>
     #   *Note:* Access to the responses hash is synchronized for thread-safety.
     #   The receiver thread and response_handlers cannot process new responses
@@ -2578,7 +2874,7 @@ module Net
     #   thread, but will not modify any responses after adding them to the
     #   responses hash.
     #
-    # ===== Clearing responses
+    # ==== Clearing responses
     #
     # Previously unhandled responses are automatically cleared before entering a
     # mailbox with #select or #examine.  Long-lived connections can receive many
@@ -2587,7 +2883,7 @@ module Net
     # the block, or remove responses with #extract_responses, #clear_responses,
     # or #add_response_handler.
     #
-    # ===== Missing responses
+    # ==== 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
@@ -2608,7 +2904,7 @@ module Net
         when :raise
           raise ArgumentError, RESPONSES_DEPRECATION_MSG
         when :warn
-          warn(RESPONSES_DEPRECATION_MSG, uplevel: 1)
+          warn(RESPONSES_DEPRECATION_MSG, uplevel: 1, category: :deprecated)
         when :frozen_dup
           synchronize {
             responses = @responses.transform_values(&:freeze)
@@ -2957,19 +3253,100 @@ 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
+
+    RETURN_WHOLE = /\ARETURN\z/i
+    RETURN_START = /\ARETURN\b/i
+    private_constant :RETURN_WHOLE, :RETURN_START
+
+    def search_args(keys, charset_arg = nil, return: nil, charset: nil)
+      {return:} => {return: return_kw}
+      case [return_kw, keys]
+      in [nil, Array[RETURN_WHOLE, return_opts, *keys]]
+        return_opts = convert_return_opts(return_opts)
+        esearch = true
+      in [nil => return_opts, RETURN_START]
+        esearch = true
+      in [nil => return_opts, keys]
+        esearch = false
+      in [_, Array[RETURN_WHOLE, _, *] | RETURN_START]
+        raise ArgumentError, "conflicting return options"
+      in [_, Array[RETURN_WHOLE, _, *]] # workaround for https://bugs.ruby-lang.org/issues/20956
+        raise ArgumentError, "conflicting return options"
+      in [_, RETURN_START]              # workaround for https://bugs.ruby-lang.org/issues/20956
+        raise ArgumentError, "conflicting return options"
+      in [return_opts, keys]
+        return_opts = convert_return_opts(return_opts)
+        esearch = true
       end
+      if charset && charset_arg
+        raise ArgumentError, "multiple charset arguments"
+      end
+      charset ||= charset_arg
+      # NOTE: not handling combined RETURN and CHARSET for raw strings
+      if charset && keys in /\ACHARSET\b/i | Array[/\ACHARSET\z/i, *]
+        raise ArgumentError, "multiple charset arguments"
+      end
+      args = normalize_searching_criteria(keys)
+      args.prepend("CHARSET", charset)     if charset
+      args.prepend("RETURN",  return_opts) if return_opts
+      return args, esearch
+    end
+
+    def convert_return_opts(unconverted)
+      return_opts = Array.try_convert(unconverted) or
+        raise TypeError, "expected return options to be Array, got %s" % [
+          unconverted.class
+        ]
+      return_opts.map {|opt|
+        case opt
+        when Symbol then opt.to_s
+        when Range  then partial_range_last_or_seqset(opt)
+        else             opt
+        end
+      }
+    end
+
+    def partial_range_last_or_seqset(range)
+      case [range.begin, range.end]
+      in [Integer => first, Integer => last] if first.negative? && last.negative?
+        # partial-range-last [RFC9394]
+        first <= last or raise DataFormatError, "empty range: %p" % [range]
+        "#{first}:#{last}"
+      else
+        SequenceSet[range]
+      end
+    end
+
+    def search_internal(cmd, ...)
+      args, esearch = search_args(...)
       synchronize do
-        if charset
-          send_command(cmd, "CHARSET", charset, *keys)
+        tagged = send_command(cmd, *args)
+        tag    = tagged.tag
+        # Only the last ESEARCH or SEARCH is used.  Excess results are ignored.
+        esearch_result = extract_responses("ESEARCH") {|response|
+          response in ESearchResult(tag: ^tag)
+        }.last
+        search_result = clear_responses("SEARCH").last
+        if esearch_result
+          # silently ignore SEARCH results, if any
+          esearch_result
+        elsif search_result
+          # warn EXPECTED_ESEARCH_RESULT if esearch
+          search_result
+        elsif esearch
+          # warn NO_SEARCH_RESPONSE
+          ESearchResult[tag:, uid: cmd.start_with?("UID ")]
         else
-          send_command(cmd, *keys)
+          # warn NO_SEARCH_RESPONSE
+          SearchResult[]
         end
-        clear_responses("SEARCH").last || []
       end
     end
 
@@ -2990,9 +3367,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
@@ -3000,7 +3377,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
@@ -3011,15 +3388,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 || []
@@ -3027,25 +3400,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
 
@@ -3099,6 +3486,7 @@ require_relative "imap/errors"
 require_relative "imap/config"
 require_relative "imap/command_data"
 require_relative "imap/data_encoding"
+require_relative "imap/data_lite"
 require_relative "imap/flags"
 require_relative "imap/response_data"
 require_relative "imap/response_parser"