net-imap 0.4.10 → 0.5.8

data/lib/net/imap.rb

@@ -25,8 +25,8 @@ module Net
 
   # Net::IMAP implements Internet Message Access Protocol (\IMAP) client
   # functionality.  The protocol is described
-  # in {IMAP4rev1 [RFC3501]}[https://tools.ietf.org/html/rfc3501]
-  # and {IMAP4rev2 [RFC9051]}[https://tools.ietf.org/html/rfc9051].
+  # in {IMAP4rev1 [RFC3501]}[https://www.rfc-editor.org/rfc/rfc3501]
+  # and {IMAP4rev2 [RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051].
   #
   # == \IMAP Overview
   #
@@ -43,10 +43,18 @@ 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.
+  #
+  # See #connection_state.
+  #
   # === Sequence numbers and UIDs
   #
   # Messages have two sorts of identifiers: message sequence
@@ -199,6 +207,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 +304,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.
   #
@@ -288,6 +333,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.
@@ -297,15 +344,15 @@ module Net
   # === Core \IMAP commands
   #
   # The following commands are defined either by
-  # the [IMAP4rev1[https://tools.ietf.org/html/rfc3501]] base specification, or
+  # the [IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501]] base specification, or
   # by one of the following extensions:
-  # [IDLE[https://tools.ietf.org/html/rfc2177]],
-  # [NAMESPACE[https://tools.ietf.org/html/rfc2342]],
-  # [UNSELECT[https://tools.ietf.org/html/rfc3691]],
-  # [ENABLE[https://tools.ietf.org/html/rfc5161]],
-  # [MOVE[https://tools.ietf.org/html/rfc6851]].
+  # [IDLE[https://www.rfc-editor.org/rfc/rfc2177]],
+  # [NAMESPACE[https://www.rfc-editor.org/rfc/rfc2342]],
+  # [UNSELECT[https://www.rfc-editor.org/rfc/rfc3691]],
+  # [ENABLE[https://www.rfc-editor.org/rfc/rfc5161]],
+  # [MOVE[https://www.rfc-editor.org/rfc/rfc6851]].
   # These extensions are widely supported by modern IMAP4rev1 servers and have
-  # all been integrated into [IMAP4rev2[https://tools.ietf.org/html/rfc9051]].
+  # all been integrated into [IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051]].
   # <em>*NOTE:* Net::IMAP doesn't support IMAP4rev2 yet.</em>
   #
   # ==== Any state
@@ -315,37 +362,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.
@@ -367,12 +413,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.
@@ -393,7 +439,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.
@@ -402,7 +448,7 @@ module Net
   #
   # ==== RFC9051: +IMAP4rev2+
   #
-  # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is not supported
+  # Although IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] is not supported
   # yet, Net::IMAP supports several extensions that have been folded into it:
   # +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+, +UNSELECT+,
   # <tt>STATUS=SIZE</tt>, and the fetch side of +BINARY+.
@@ -412,7 +458,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+
@@ -422,13 +468,13 @@ module Net
   # - #setquota: sets the resource limits for a given quota root.
   #
   # ==== RFC2177: +IDLE+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
   # - #idle: Allows the server to send updates to the client, without the client
   #   needing to poll using #noop.
   #
   # ==== RFC2342: +NAMESPACE+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
   # - #namespace: Returns mailbox namespaces, with path prefixes and delimiters.
   #
@@ -437,7 +483,7 @@ module Net
   #
   # ==== RFC3516: +BINARY+
   # The fetch side of +BINARY+ has been folded into
-  # IMAP4rev2[https://tools.ietf.org/html/rfc9051].
+  # IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].
   # - Updates #fetch and #uid_fetch with the +BINARY+, +BINARY.PEEK+, and
   #   +BINARY.SIZE+ items.  See FetchData#binary and FetchData#binary_size.
   #
@@ -445,9 +491,9 @@ module Net
   #   *NOTE:* The binary extension the #append command is _not_ supported yet.
   #
   # ==== RFC3691: +UNSELECT+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/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+
@@ -457,19 +503,23 @@ module Net
   #   *NOTE:* +DELETEACL+, +LISTRIGHTS+, and +MYRIGHTS+ are not supported yet.
   #
   # ==== RFC4315: +UIDPLUS+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
   # - #uid_expunge: Restricts #expunge to only remove the specified UIDs.
   # - Updates #select, #examine with the +UIDNOTSTICKY+ ResponseCode
   # - Updates #append with the +APPENDUID+ ResponseCode
   # - Updates #copy, #move with the +COPYUID+ ResponseCode
   #
+  # ==== RFC4731: +ESEARCH+
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].
+  # - Updates #search, #uid_search with +return+ options and ESearchResult.
+  #
   # ==== RFC4959: +SASL-IR+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].
   # - Updates #authenticate with the option to send an initial response.
   #
   # ==== RFC5161: +ENABLE+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
   # - #enable: Enables backwards incompatible server extensions.
   #
@@ -493,7 +543,7 @@ module Net
   # +X-GM-THRID+, but Gmail does not support it (as of 2023-11-10).
   #
   # ==== RFC6851: +MOVE+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
   # - #move, #uid_move: Moves the specified messages to the end of the
   #   specified destination mailbox, expunging them from the current mailbox.
@@ -528,6 +578,17 @@ module Net
   #   See FetchData#emailid and FetchData#emailid.
   # - Updates #status with support for the +MAILBOXID+ status attribute.
   #
+  # ==== RFC9394: +PARTIAL+
+  # - Updates #search, #uid_search with the +PARTIAL+ return option which adds
+  #   ESearchResult#partial return data.
+  # - Updates #uid_fetch with the +partial+ modifier.
+  #
+  # ==== RFC9586: +UIDONLY+
+  # - Updates #enable with +UIDONLY+ parameter.
+  # - Updates #uid_fetch and #uid_store to return +UIDFETCH+ response.
+  # - Updates #expunge and #uid_expunge to return +VANISHED+ response.
+  # - Prohibits use of message sequence numbers in responses or requests.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
@@ -558,57 +619,57 @@ module Net
   #   Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC 2180, DOI
   #   10.17487/RFC2180, July 1997, <https://www.rfc-editor.org/info/rfc2180>.
   #
-  # [UTF7[https://tools.ietf.org/html/rfc2152]]::
+  # [UTF7[https://www.rfc-editor.org/rfc/rfc2152]]::
   #   Goldsmith, D. and M. Davis, "UTF-7 A Mail-Safe Transformation Format of
   #   Unicode", RFC 2152, DOI 10.17487/RFC2152, May 1997,
   #   <https://www.rfc-editor.org/info/rfc2152>.
   #
   # === Message envelope and body structure
   #
-  # [RFC5322[https://tools.ietf.org/html/rfc5322]]::
+  # [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]::
   #   Resnick, P., Ed., "Internet Message Format",
   #   RFC 5322, DOI 10.17487/RFC5322, October 2008,
   #   <https://www.rfc-editor.org/info/rfc5322>.
   #
   #   <em>Note: obsoletes</em>
-  #   RFC-2822[https://tools.ietf.org/html/rfc2822]<em> (April 2001) and</em>
-  #   RFC-822[https://tools.ietf.org/html/rfc822]<em> (August 1982).</em>
+  #   RFC-2822[https://www.rfc-editor.org/rfc/rfc2822]<em> (April 2001) and</em>
+  #   RFC-822[https://www.rfc-editor.org/rfc/rfc822]<em> (August 1982).</em>
   #
-  # [CHARSET[https://tools.ietf.org/html/rfc2978]]::
+  # [CHARSET[https://www.rfc-editor.org/rfc/rfc2978]]::
   #   Freed, N. and J. Postel, "IANA Charset Registration Procedures", BCP 19,
   #   RFC 2978, DOI 10.17487/RFC2978, October 2000,
   #   <https://www.rfc-editor.org/info/rfc2978>.
   #
-  # [DISPOSITION[https://tools.ietf.org/html/rfc2183]]::
+  # [DISPOSITION[https://www.rfc-editor.org/rfc/rfc2183]]::
   #    Troost, R., Dorner, S., and K. Moore, Ed., "Communicating Presentation
   #    Information in Internet Messages: The Content-Disposition Header
   #    Field", RFC 2183, DOI 10.17487/RFC2183, August 1997,
   #    <https://www.rfc-editor.org/info/rfc2183>.
   #
-  # [MIME-IMB[https://tools.ietf.org/html/rfc2045]]::
+  # [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]]::
   #    Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions
   #    (MIME) Part One: Format of Internet Message Bodies",
   #    RFC 2045, DOI 10.17487/RFC2045, November 1996,
   #    <https://www.rfc-editor.org/info/rfc2045>.
   #
-  # [MIME-IMT[https://tools.ietf.org/html/rfc2046]]::
+  # [MIME-IMT[https://www.rfc-editor.org/rfc/rfc2046]]::
   #    Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions
   #    (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046,
   #    November 1996, <https://www.rfc-editor.org/info/rfc2046>.
   #
-  # [MIME-HDRS[https://tools.ietf.org/html/rfc2047]]::
+  # [MIME-HDRS[https://www.rfc-editor.org/rfc/rfc2047]]::
   #    Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three:
   #    Message Header Extensions for Non-ASCII Text",
   #    RFC 2047, DOI 10.17487/RFC2047, November 1996,
   #    <https://www.rfc-editor.org/info/rfc2047>.
   #
-  # [RFC2231[https://tools.ietf.org/html/rfc2231]]::
+  # [RFC2231[https://www.rfc-editor.org/rfc/rfc2231]]::
   #    Freed, N. and K. Moore, "MIME Parameter Value and Encoded Word
   #    Extensions: Character Sets, Languages, and Continuations",
   #    RFC 2231, DOI 10.17487/RFC2231, November 1997,
   #    <https://www.rfc-editor.org/info/rfc2231>.
   #
-  # [I18n-HDRS[https://tools.ietf.org/html/rfc6532]]::
+  # [I18n-HDRS[https://www.rfc-editor.org/rfc/rfc6532]]::
   #    Yang, A., Steele, S., and N. Freed, "Internationalized Email Headers",
   #    RFC 6532, DOI 10.17487/RFC6532, February 2012,
   #    <https://www.rfc-editor.org/info/rfc6532>.
@@ -624,12 +685,12 @@ module Net
   #    RFC 2557, DOI 10.17487/RFC2557, March 1999,
   #    <https://www.rfc-editor.org/info/rfc2557>.
   #
-  # [MD5[https://tools.ietf.org/html/rfc1864]]::
+  # [MD5[https://www.rfc-editor.org/rfc/rfc1864]]::
   #    Myers, J. and M. Rose, "The Content-MD5 Header Field",
   #    RFC 1864, DOI 10.17487/RFC1864, October 1995,
   #    <https://www.rfc-editor.org/info/rfc1864>.
   #
-  # [RFC3503[https://tools.ietf.org/html/rfc3503]]::
+  # [RFC3503[https://www.rfc-editor.org/rfc/rfc3503]]::
   #    Melnikov, A., "Message Disposition Notification (MDN)
   #    profile for Internet Message Access Protocol (IMAP)",
   #    RFC 3503, DOI 10.17487/RFC3503, March 2003,
@@ -637,27 +698,27 @@ module Net
   #
   # === \IMAP Extensions
   #
-  # [QUOTA[https://tools.ietf.org/html/rfc9208]]::
+  # [QUOTA[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>.
   #
   #   <em>Note: obsoletes</em>
-  #   RFC-2087[https://tools.ietf.org/html/rfc2087]<em> (January 1997)</em>.
+  #   RFC-2087[https://www.rfc-editor.org/rfc/rfc2087]<em> (January 1997)</em>.
   #   <em>Net::IMAP does not fully support the RFC9208 updates yet.</em>
-  # [IDLE[https://tools.ietf.org/html/rfc2177]]::
+  # [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]]::
+  # [NAMESPACE[https://www.rfc-editor.org/rfc/rfc2342]]::
   #   Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342,
   #   DOI 10.17487/RFC2342, May 1998, <https://www.rfc-editor.org/info/rfc2342>.
-  # [ID[https://tools.ietf.org/html/rfc2971]]::
+  # [ID[https://www.rfc-editor.org/rfc/rfc2971]]::
   #   Showalter, T., "IMAP4 ID extension", RFC 2971, DOI 10.17487/RFC2971,
   #   October 2000, <https://www.rfc-editor.org/info/rfc2971>.
-  # [BINARY[https://tools.ietf.org/html/rfc3516]]::
+  # [BINARY[https://www.rfc-editor.org/rfc/rfc3516]]::
   #   Nerenberg, L., "IMAP4 Binary Content Extension", RFC 3516,
   #   DOI 10.17487/RFC3516, April 2003,
   #   <https://www.rfc-editor.org/info/rfc3516>.
-  # [ACL[https://tools.ietf.org/html/rfc4314]]::
+  # [ACL[https://www.rfc-editor.org/rfc/rfc4314]]::
   #   Melnikov, A., "IMAP4 Access Control List (ACL) Extension", RFC 4314,
   #   DOI 10.17487/RFC4314, December 2005,
   #   <https://www.rfc-editor.org/info/rfc4314>.
@@ -665,36 +726,46 @@ module Net
   #   Crispin, M., "Internet Message Access Protocol (\IMAP) - UIDPLUS
   #   extension", RFC 4315, DOI 10.17487/RFC4315, December 2005,
   #   <https://www.rfc-editor.org/info/rfc4315>.
-  # [SORT[https://tools.ietf.org/html/rfc5256]]::
+  # [SORT[https://www.rfc-editor.org/rfc/rfc5256]]::
   #   Crispin, M. and K. Murchison, "Internet Message Access Protocol - SORT and
   #   THREAD Extensions", RFC 5256, DOI 10.17487/RFC5256, June 2008,
   #   <https://www.rfc-editor.org/info/rfc5256>.
-  # [THREAD[https://tools.ietf.org/html/rfc5256]]::
+  # [THREAD[https://www.rfc-editor.org/rfc/rfc5256]]::
   #   Crispin, M. and K. Murchison, "Internet Message Access Protocol - SORT and
   #   THREAD Extensions", RFC 5256, DOI 10.17487/RFC5256, June 2008,
   #   <https://www.rfc-editor.org/info/rfc5256>.
   # [RFC5530[https://www.rfc-editor.org/rfc/rfc5530.html]]::
   #   Gulbrandsen, A., "IMAP Response Codes", RFC 5530, DOI 10.17487/RFC5530,
   #   May 2009, <https://www.rfc-editor.org/info/rfc5530>.
-  # [MOVE[https://tools.ietf.org/html/rfc6851]]::
+  # [MOVE[https://www.rfc-editor.org/rfc/rfc6851]]::
   #   Gulbrandsen, A. and N. Freed, Ed., "Internet Message Access Protocol
   #   (\IMAP) - MOVE Extension", RFC 6851, DOI 10.17487/RFC6851, January 2013,
   #   <https://www.rfc-editor.org/info/rfc6851>.
-  # [UTF8=ACCEPT[https://tools.ietf.org/html/rfc6855]]::
-  # [UTF8=ONLY[https://tools.ietf.org/html/rfc6855]]::
+  # [UTF8=ACCEPT[https://www.rfc-editor.org/rfc/rfc6855]]::
+  # [UTF8=ONLY[https://www.rfc-editor.org/rfc/rfc6855]]::
   #   Resnick, P., Ed., Newman, C., Ed., and S. Shen, Ed.,
   #   "IMAP Support for UTF-8", RFC 6855, DOI 10.17487/RFC6855, March 2013,
   #   <https://www.rfc-editor.org/info/rfc6855>.
-  # [CONDSTORE[https://tools.ietf.org/html/rfc7162]]::
-  # [QRESYNC[https://tools.ietf.org/html/rfc7162]]::
+  # [CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162]]::
+  # [QRESYNC[https://www.rfc-editor.org/rfc/rfc7162]]::
   #   Melnikov, A. and D. Cridland, "IMAP Extensions: Quick Flag Changes
   #   Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization
   #   (QRESYNC)", RFC 7162, DOI 10.17487/RFC7162, May 2014,
   #   <https://www.rfc-editor.org/info/rfc7162>.
-  # [OBJECTID[https://tools.ietf.org/html/rfc8474]]::
+  # [OBJECTID[https://www.rfc-editor.org/rfc/rfc8474]]::
   #   Gondwana, B., Ed., "IMAP Extension for Object Identifiers",
   #   RFC 8474, DOI 10.17487/RFC8474, September 2018,
   #   <https://www.rfc-editor.org/info/rfc8474>.
+  # [PARTIAL[https://www.rfc-editor.org/info/rfc9394]]::
+  #   Melnikov, A., Achuthan, A., Nagulakonda, V., and L. Alves,
+  #   "IMAP PARTIAL Extension for Paged SEARCH and FETCH", RFC 9394,
+  #   DOI 10.17487/RFC9394, June 2023,
+  #   <https://www.rfc-editor.org/info/rfc9394>.
+  # [UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.pdf]]::
+  #   Melnikov, A., Achuthan, A., Nagulakonda, V., Singh, A., and L. Alves,
+  #   "\IMAP Extension for Using and Returning Unique Identifiers (UIDs) Only",
+  #   RFC 9586, DOI 10.17487/RFC9586, May 2024,
+  #   <https://www.rfc-editor.org/info/rfc9586>.
   #
   # === IANA registries
   # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
@@ -708,7 +779,7 @@ module Net
   # * {GSSAPI/Kerberos/SASL Service Names}[https://www.iana.org/assignments/gssapi-service-names/gssapi-service-names.xhtml]:
   #   +imap+
   # * {Character sets}[https://www.iana.org/assignments/character-sets/character-sets.xhtml]
-  # ===== For currently unsupported features:
+  # ==== For currently unsupported features:
   # * {IMAP Quota Resource Types}[http://www.iana.org/assignments/imap4-capabilities#imap-capabilities-2]
   # * {LIST-EXTENDED options and responses}[https://www.iana.org/assignments/imap-list-extended/imap-list-extended.xhtml]
   # * {IMAP METADATA Server Entry and Mailbox Entry Registries}[https://www.iana.org/assignments/imap-metadata/imap-metadata.xhtml]
@@ -717,7 +788,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.10"
+    VERSION = "0.5.8"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -725,9 +796,12 @@ module Net
       "UTF8=ONLY" => "UTF8=ACCEPT",
     }.freeze
 
-    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__)
+    dir = File.expand_path("imap", __dir__)
+    autoload :ConnectionState,        "#{dir}/connection_state"
+    autoload :ResponseReader,         "#{dir}/response_reader"
+    autoload :SASL,                   "#{dir}/sasl"
+    autoload :SASLAdapter,            "#{dir}/sasl_adapter"
+    autoload :StringPrep,             "#{dir}/stringprep"
 
     include MonitorMixin
     if defined?(OpenSSL::SSL)
@@ -735,14 +809,17 @@ 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.
+    # Delegates to {Net::IMAP.config.debug}[rdoc-ref:Config#debug].
+    def self.debug; config.debug end
 
-    # Sets the debug mode.
+    # Sets the global debug mode.
+    # Delegates to {Net::IMAP.config.debug=}[rdoc-ref:Config#debug=].
     def self.debug=(val)
-      return @@debug = val
+      config.debug = val
     end
 
     # The default port for IMAP connections, port 143
@@ -761,16 +838,37 @@ 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
 
-    # 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
+    # The client configuration.  See Net::IMAP::Config.
+    #
+    # By default, the client's local configuration inherits from the global
+    # Net::IMAP.config.
+    attr_reader :config
+
+    ##
+    # :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.
-    attr_reader :idle_response_timeout
+    # 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
@@ -793,6 +891,67 @@ module Net
     # Returns +false+ for a plaintext connection.
     attr_reader :ssl_ctx_params
 
+    # Returns the current connection state.
+    #
+    # Once an IMAP connection is established, the connection is in one of four
+    # states: +not_authenticated+, +authenticated+, +selected+, and +logout+.
+    # Most commands are valid only in certain states.
+    #
+    # The connection state object responds to +to_sym+ and +name+ with the name
+    # of the current connection state, as a Symbol or String.  Future versions
+    # of +net-imap+ may store additional information on the state object.
+    #
+    # From {RFC9051}[https://www.rfc-editor.org/rfc/rfc9051#section-3]:
+    #                    +----------------------+
+    #                    |connection established|
+    #                    +----------------------+
+    #                               ||
+    #                               \/
+    #             +--------------------------------------+
+    #             |          server greeting             |
+    #             +--------------------------------------+
+    #                       || (1)       || (2)        || (3)
+    #                       \/           ||            ||
+    #             +-----------------+    ||            ||
+    #             |Not Authenticated|    ||            ||
+    #             +-----------------+    ||            ||
+    #              || (7)   || (4)       ||            ||
+    #              ||       \/           \/            ||
+    #              ||     +----------------+           ||
+    #              ||     | Authenticated  |<=++       ||
+    #              ||     +----------------+  ||       ||
+    #              ||       || (7)   || (5)   || (6)   ||
+    #              ||       ||       \/       ||       ||
+    #              ||       ||    +--------+  ||       ||
+    #              ||       ||    |Selected|==++       ||
+    #              ||       ||    +--------+           ||
+    #              ||       ||       || (7)            ||
+    #              \/       \/       \/                \/
+    #             +--------------------------------------+
+    #             |               Logout                 |
+    #             +--------------------------------------+
+    #                               ||
+    #                               \/
+    #                 +-------------------------------+
+    #                 |both sides close the connection|
+    #                 +-------------------------------+
+    #
+    # >>>
+    #   Legend for the above diagram:
+    #
+    #   1. connection without pre-authentication (+OK+ #greeting)
+    #   2. pre-authenticated connection (+PREAUTH+ #greeting)
+    #   3. rejected connection (+BYE+ #greeting)
+    #   4. successful #login or #authenticate command
+    #   5. successful #select or #examine command
+    #   6. #close or #unselect command, unsolicited +CLOSED+ response code, or
+    #      failed #select or #examine command
+    #   7. #logout command, server shutdown, or connection closed
+    #
+    # Before the server greeting, the state is +not_authenticated+.
+    # After the connection closes, the state remains +logout+.
+    attr_reader :connection_state
+
     # Creates a new Net::IMAP object and connects it to the specified
     # +host+.
     #
@@ -809,18 +968,50 @@ 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.
+    #
+    #   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.
+    #
+    #   >>>
+    #     *NOTE:* +config+ does not set #config directly---it sets the _parent_
+    #     config for inheritance.  Every client creates its own unique #config.
     #
-    # [open_timeout]
-    #   Seconds to wait until a connection is opened
-    # [idle_response_timeout]
-    #   Seconds to wait until an IDLE response is received
+    #   All other keyword arguments are forwarded to Net::IMAP::Config.new, to
+    #   initialize the client's #config. For example:
     #
-    # See DeprecatedClientOptions.new for deprecated arguments.
+    #   [{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
     #
-    # Connect to cleartext port 143 at mail.example.com and recieve the server greeting:
+    # Connect to cleartext port 143 at mail.example.com and receive the server greeting:
     #   imap = Net::IMAP.new('mail.example.com', ssl: false) # => #<Net::IMAP:0x00007f79b0872bd0>
     #   imap.port          => 143
     #   imap.tls_verified? => false
@@ -871,14 +1062,13 @@ module Net
     # [Net::IMAP::ByeResponseError]
     #   Connected to the host successfully, but it immediately said goodbye.
     #
-    def initialize(host, port: nil, ssl:  nil,
-                   open_timeout: 30, idle_response_timeout: 5)
+    def initialize(host, port: nil, ssl: nil, response_handlers: nil,
+                   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
@@ -887,14 +1077,17 @@ module Net
       @exception = nil
       @greeting = nil
       @capabilities = nil
+      @tls_verified = false
+      @connection_state = ConnectionState::NotAuthenticated.new
 
-      # Client Protocol Reciever
-      @parser = ResponseParser.new
+      # Client Protocol Receiver
+      @parser = ResponseParser.new(config: @config)
       @responses = Hash.new {|h, k| h[k] = [] }
       @response_handlers = []
       @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"
@@ -908,13 +1101,10 @@ module Net
       @logout_command_tag = nil
 
       # Connection
-      @tls_verified = false
       @sock = tcp_socket(@host, @port)
+      @reader = ResponseReader.new(self, @sock)
       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,16 +1112,12 @@ 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!
     def disconnect
       return if disconnected?
+      state_logout!
       begin
         begin
           # try to call SSL::SSLSocket#io.
@@ -1095,12 +1281,12 @@ module Net
     #      )
     #    end
     #
-    # See [ID[https://tools.ietf.org/html/rfc2971]] for field definitions.
+    # See [ID[https://www.rfc-editor.org/rfc/rfc2971]] for field definitions.
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +ID+
-    # [RFC2971[https://tools.ietf.org/html/rfc2971]].
+    # [RFC2971[https://www.rfc-editor.org/rfc/rfc2971]].
     def id(client_id=nil)
       synchronize do
         send_command("ID", ClientID.new(client_id))
@@ -1170,6 +1356,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
@@ -1179,7 +1369,7 @@ module Net
     #
     # Related: Net::IMAP.new, #login, #authenticate
     #
-    # ===== Capability
+    # ==== Capability
     # Clients should not call #starttls unless the server advertises the
     # +STARTTLS+ capability.
     #
@@ -1188,17 +1378,25 @@ module Net
     #
     def starttls(**options)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options)
-      send_command("STARTTLS") do |resp|
+      error = nil
+      ok = send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
           clear_cached_capabilities
           clear_responses
           start_tls_session
         end
+      rescue Exception => error
+        raise # note that the error backtrace is in the receiver_thread
       end
+      if error
+        disconnect
+        raise error
+      end
+      ok
     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 +1405,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 +1505,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 do state_authenticated! _1 end
     end
 
     # Sends a {LOGIN command [IMAP4rev1 §6.2.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.3]
@@ -1340,16 +1524,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.
@@ -1357,8 +1537,11 @@ 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 }
+        .tap do state_authenticated! _1 end
     end
 
     # Sends a {SELECT command [IMAP4rev1 §6.3.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.1]
@@ -1382,7 +1565,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"
@@ -1398,8 +1581,10 @@ module Net
       args = ["SELECT", mailbox]
       args << ["CONDSTORE"] if condstore
       synchronize do
+        state_unselected! # implicitly closes current mailbox
         @responses.clear
         send_command(*args)
+          .tap do state_selected! end
       end
     end
 
@@ -1416,8 +1601,10 @@ module Net
       args = ["EXAMINE", mailbox]
       args << ["CONDSTORE"] if condstore
       synchronize do
+        state_unselected! # implicitly closes current mailbox
         @responses.clear
         send_command(*args)
+          .tap do state_selected! end
       end
     end
 
@@ -1500,7 +1687,7 @@ module Net
     #
     # Related: #lsub, MailboxList
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   imap.create("foo/bar")
     #   imap.create("foo/baz")
@@ -1538,7 +1725,7 @@ module Net
     # servers, then folder creation (and listing, moving, etc) can lead to
     # errors.
     #
-    # From RFC2342[https://tools.ietf.org/html/rfc2342]:
+    # From RFC2342[https://www.rfc-editor.org/rfc/rfc2342]:
     # >>>
     #    <em>Although typically a server will support only a single Personal
     #    Namespace, and a single Other User's Namespace, circumstances exist
@@ -1551,7 +1738,7 @@ module Net
     #
     # Related: #list, Namespaces, Namespace
     #
-    # ===== For example:
+    # ==== For example:
     #
     #    if capable?("NAMESPACE")
     #      namespaces = imap.namespace
@@ -1565,10 +1752,10 @@ module Net
     #      end
     #    end
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
-    # The server's capabilities must include +NAMESPACE+
-    # [RFC2342[https://tools.ietf.org/html/rfc2342]].
+    # The server's capabilities must include either +IMAP4rev2+ or +NAMESPACE+
+    # [RFC2342[https://www.rfc-editor.org/rfc/rfc2342]].
     def namespace
       synchronize do
         send_command("NAMESPACE")
@@ -1604,7 +1791,7 @@ module Net
     #
     # Related: #list, MailboxList
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +XLIST+,
     # a deprecated Gmail extension (replaced by +SPECIAL-USE+).
@@ -1627,10 +1814,10 @@ module Net
     #
     # Related: #getquota, #setquota, MailboxQuotaRoot, MailboxQuota
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
+    # [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]].
     def getquotaroot(mailbox)
       synchronize do
         send_command("GETQUOTAROOT", mailbox)
@@ -1648,10 +1835,10 @@ module Net
     #
     # Related: #getquotaroot, #setquota, MailboxQuota
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
+    # [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]].
     def getquota(mailbox)
       synchronize do
         send_command("GETQUOTA", mailbox)
@@ -1666,10 +1853,10 @@ module Net
     #
     # Related: #getquota, #getquotaroot
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
+    # [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]].
     def setquota(mailbox, quota)
       if quota.nil?
         data = '()'
@@ -1686,10 +1873,10 @@ module Net
     #
     # Related: #getacl
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +ACL+
-    # [RFC4314[https://tools.ietf.org/html/rfc4314]].
+    # [RFC4314[https://www.rfc-editor.org/rfc/rfc4314]].
     def setacl(mailbox, user, rights)
       if rights.nil?
         send_command("SETACL", mailbox, user, "")
@@ -1704,10 +1891,10 @@ module Net
     #
     # Related: #setacl, MailboxACLItem
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include +ACL+
-    # [RFC4314[https://tools.ietf.org/html/rfc4314]].
+    # [RFC4314[https://www.rfc-editor.org/rfc/rfc4314]].
     def getacl(mailbox)
       synchronize do
         send_command("GETACL", mailbox)
@@ -1741,7 +1928,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.
     #
@@ -1772,12 +1959,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>
@@ -1817,7 +2004,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
@@ -1856,6 +2043,7 @@ module Net
     # Related: #unselect
     def close
       send_command("CLOSE")
+        .tap do state_authenticated! end
     end
 
     # Sends an {UNSELECT command [RFC3691 §2]}[https://www.rfc-editor.org/rfc/rfc3691#section-3]
@@ -1866,129 +2054,493 @@ module Net
     #
     # Related: #close
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
-    # The server's capabilities must include +UNSELECT+
-    # [RFC3691[https://tools.ietf.org/html/rfc3691]].
+    # The server's capabilities must include either +IMAP4rev2+ or +UNSELECT+
+    # [RFC3691[https://www.rfc-editor.org/rfc/rfc3691]].
     def unselect
       send_command("UNSELECT")
+        .tap do state_authenticated! end
     end
 
+    # call-seq:
+    #   expunge -> array of message sequence numbers
+    #   expunge -> VanishedData of UIDs
+    #
     # Sends an {EXPUNGE command [IMAP4rev1 §6.4.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.3]
-    # Sends a EXPUNGE command to permanently remove from the currently
-    # selected mailbox all messages that have the \Deleted flag set.
+    # to permanently remove all messages with the +\Deleted+ flag from the
+    # currently selected mailbox.
+    #
+    # Returns either an array of expunged message <em>sequence numbers</em> or
+    # (when the appropriate capability is enabled) VanishedData of expunged
+    # UIDs.  Previously unhandled +EXPUNGE+ or +VANISHED+ responses are merged
+    # with the direct response to this command.  <tt>VANISHED (EARLIER)</tt>
+    # responses will _not_ be merged.
+    #
+    # When no messages have been expunged, an empty array is returned,
+    # regardless of which extensions are enabled.  In a future release, an empty
+    # VanishedData may be returned, based on the currently enabled extensions.
     #
     # Related: #uid_expunge
+    #
+    # ==== Capabilities
+    #
+    # When either QRESYNC[https://www.rfc-editor.org/rfc/rfc7162] or
+    # UIDONLY[https://www.rfc-editor.org/rfc/rfc9586] are enabled, #expunge
+    # returns VanishedData, which contains UIDs---<em>not message sequence
+    # numbers</em>.
     def expunge
-      synchronize do
-        send_command("EXPUNGE")
-        clear_responses("EXPUNGE")
-      end
+      expunge_internal("EXPUNGE")
     end
 
+    # call-seq:
+    #   uid_expunge{uid_set) -> array of message sequence numbers
+    #   uid_expunge{uid_set) -> VanishedData of UIDs
+    #
     # Sends a {UID EXPUNGE command [RFC4315 §2.1]}[https://www.rfc-editor.org/rfc/rfc4315#section-2.1]
     # {[IMAP4rev2 §6.4.9]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.4.9]
     # to permanently remove all messages that have both the <tt>\\Deleted</tt>
     # flag set and a UID that is included in +uid_set+.
     #
+    # Returns the same result type as #expunge.
+    #
     # By using #uid_expunge instead of #expunge when resynchronizing with
     # the server, the client can ensure that it does not inadvertantly
     # remove any messages that have been marked as <tt>\\Deleted</tt> by other
     # clients between the time that the client was last connected and
     # the time the client resynchronizes.
     #
-    # *Note:*
-    # >>>
-    #        Although the command takes a set of UIDs for its argument, the
-    #        server still returns regular EXPUNGE responses, which contain
-    #        a <em>sequence number</em>. These will be deleted from
-    #        #responses and this method returns them as an array of
-    #        <em>sequence number</em> integers.
-    #
     # Related: #expunge
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
-    # The server's capabilities must include +UIDPLUS+
+    # The server's capabilities must include either +IMAP4rev2+ or +UIDPLUS+
     # [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]].
+    #
+    # Otherwise, #uid_expunge is updated by extensions in the same way as
+    # #expunge.
     def uid_expunge(uid_set)
-      synchronize do
-        send_command("UID EXPUNGE", MessageSet.new(uid_set))
-        clear_responses("EXPUNGE")
-      end
+      expunge_internal("UID EXPUNGE", SequenceSet.new(uid_set))
     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
+    # {"Supported return options"}[rdoc-ref:#search@Supported+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:
     #
-    # For a full list of search criteria,
+    #   imap.search(["SUBJECT", "hello", "NOT", "SEEN"])
+    #   #=> [1, 6, 7, 8]
+    #
+    # 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>
+    #
+    # ==== Supported return options
+    #
+    # For full definitions of the standard return options and return data, see
+    # the relevant RFCs.
+    #
+    # [+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.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
+    # [+COUNT+]
+    #    Returns ESearchResult#count with the number of matching messages.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
+    # [+MAX+]
+    #    Returns ESearchResult#max with the highest matching sequence number or
+    #    UID.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
+    # [+MIN+]
+    #    Returns ESearchResult#min with the lowest matching sequence number or
+    #    UID.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
+    # [+PARTIAL+ _range_]
+    #    Returns ESearchResult#partial with a SequenceSet of a subset of
+    #    matching sequence numbers or UIDs, as selected by _range_.  As with
+    #    sequence numbers, the first result is +1+: <tt>1..500</tt> selects the
+    #    first 500 search results (in mailbox order), <tt>501..1000</tt> the
+    #    second 500, and so on.  _range_ may also be negative: <tt>-500..-1</tt>
+    #    selects the last 500 search results.
+    #
+    #    <em>Requires either the <tt>CONTEXT=SEARCH</tt> or +PARTIAL+ capabability.</em>
+    #    {[RFC5267]}[https://rfc-editor.org/rfc/rfc5267]
+    #    {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394]
+    #
+    # ===== +MODSEQ+ return data
+    #
+    # 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
+    # unsupported search return options and will parse unsupported 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]
+    #
+    # [+SAVEDBEFORE+ _date_]
+    # [+SAVEDON+ _date_]
+    # [+SAVEDSINCE+ _date_]
+    #   Matches when the save date is earlier than, on, or later than _date_.
+    #
+    #   <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]].
     #
-    # ===== Capabilities
+    # 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
+    # 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)
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled,
+    # the +SEARCH+ command is prohibited.  Use #uid_search instead.
+    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).
@@ -1997,9 +2549,19 @@ 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.
+    #
+    # ==== Capabilities
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled,
+    # #uid_search must be used instead of #search, and the <tt><message
+    # set></tt> search criterion is prohibited.  Use +ALL+ or <tt>UID
+    # sequence-set</tt> instead.
+    #
+    # Otherwise, #uid_search is updated by extensions in the same way as
+    # #search.
+    def uid_search(...)
+      search_internal("UID SEARCH", ...)
     end
 
     # :call-seq:
@@ -2008,26 +2570,21 @@ module Net
     # Sends a {FETCH command [IMAP4rev1 §6.4.5]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.5]
     # to retrieve data associated with a message in the mailbox.
     #
-    # The +set+ parameter is a number or a range between two numbers,
-    # or an array of those.  The number is a message sequence number,
-    # where -1 represents a '*' for use in range notation like 100..-1
-    # being interpreted as '100:*'.  Beware that the +exclude_end?+
-    # property of a Range object is ignored, and the contents of a
-    # range are independent of the order of the range endpoints as per
-    # the protocol specification, so 1...5, 5..1 and 5...1 are all
-    # equivalent to 1..5.
+    # +set+ is the message sequence numbers to fetch, and may be any valid input
+    # to {SequenceSet[...]}[rdoc-ref:SequenceSet@Creating+sequence+sets].
+    # (For UIDs, use #uid_fetch instead.)
     #
-    # +attr+ is a list of attributes to fetch; see the documentation
-    # for FetchData for a list of valid attributes.
+    # +attr+ is a list of attributes to fetch; see FetchStruct documentation for
+    # a list of supported attributes.
     #
     # +changedsince+ is an optional integer mod-sequence.  It limits results to
     # messages with a mod-sequence greater than +changedsince+.
     #
     # The return value is an array of FetchData.
     #
-    # Related: #uid_search, FetchData
+    # Related: #uid_fetch, FetchData
     #
-    # ===== For example:
+    # ==== For example:
     #
     #   p imap.fetch(6..8, "UID")
     #   #=> [#<Net::IMAP::FetchData seqno=6, attr={"UID"=>98}>, \\
@@ -2045,39 +2602,82 @@ 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.
+    # Many extensions define new message +attr+ names.  See FetchStruct for a
+    # list of supported extension fields.
     #
     # The server's capabilities must include +CONDSTORE+
-    # {[RFC7162]}[https://tools.ietf.org/html/rfc7162] in order to use the
+    # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162] in order to use the
     # +changedsince+ argument.  Using +changedsince+ implicitly enables the
     # +CONDSTORE+ extension.
-    def fetch(set, attr, mod = nil, changedsince: nil)
-      fetch_internal("FETCH", set, attr, mod, changedsince: changedsince)
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled, the
+    # +FETCH+ command is prohibited.  Use #uid_fetch instead.
+    def fetch(...)
+      fetch_internal("FETCH", ...)
     end
 
     # :call-seq:
-    #   uid_fetch(set, attr, changedsince: nil) -> array of FetchData
+    #   uid_fetch(set, attr, changedsince: nil, partial: nil) -> array of FetchData (or UIDFetchData)
     #
     # Sends a {UID FETCH command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
     # to retrieve data associated with a message in the mailbox.
     #
-    # Similar to #fetch, but the +set+ parameter contains unique identifiers
-    # instead of message sequence numbers.
+    # +set+ is the message UIDs to fetch, and may be any valid input to
+    # {SequenceSet[...]}[rdoc-ref:SequenceSet@Creating+sequence+sets].
+    # (For message sequence numbers, use #fetch instead.)
     #
+    # +attr+ behaves the same as with #fetch.
     # >>>
     #   *Note:* Servers _MUST_ implicitly include the +UID+ message data item as
     #   part of any +FETCH+ response caused by a +UID+ command, regardless of
     #   whether a +UID+ was specified as a message data item to the +FETCH+.
     #
+    # +changedsince+ (optional) behaves the same as with #fetch.
+    #
+    # +partial+ is an optional range to limit the number of results returned.
+    # It's useful when +set+ contains an unknown number of messages.
+    # <tt>1..500</tt> returns the first 500 messages in +set+ (in mailbox
+    # order), <tt>501..1000</tt> the second 500, and so on.  +partial+ may also
+    # be negative: <tt>-500..-1</tt> selects the last 500 messages in +set+.
+    # <em>Requires the +PARTIAL+ capabability.</em>
+    # {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394]
+    #
+    # For example:
+    #
+    #   # Without partial, the size of the results may be unknown beforehand:
+    #   results = imap.uid_fetch(next_uid_to_fetch.., %w(UID FLAGS))
+    #   # ... maybe wait for a long time ... and allocate a lot of memory ...
+    #   results.size # => 0..2**32-1
+    #   process results # may also take a long time and use a lot of memory...
+    #
+    #   # Using partial, the results may be paginated:
+    #   loop do
+    #     results = imap.uid_fetch(next_uid_to_fetch.., %w(UID FLAGS),
+    #                              partial: 1..500)
+    #     # fetch should return quickly and allocate little memory
+    #     results.size # => 0..500
+    #     break if results.empty?
+    #     next_uid_to_fetch = results.last.uid + 1
+    #     process results
+    #   end
+    #
     # Related: #fetch, FetchData
     #
-    # ===== Capabilities
-    # Same as #fetch.
-    def uid_fetch(set, attr, mod = nil, changedsince: nil)
-      fetch_internal("UID FETCH", set, attr, mod, changedsince: changedsince)
+    # ==== Capabilities
+    #
+    # The server's capabilities must include +PARTIAL+
+    # {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394] in order to use the
+    # +partial+ argument.
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled,
+    # #uid_fetch must be used instead of #fetch, and UIDFetchData will be
+    # returned instead of FetchData.
+    #
+    # Otherwise, #uid_fetch is updated by extensions in the same way as #fetch.
+    def uid_fetch(...)
+      fetch_internal("UID FETCH", ...)
     end
 
     # :call-seq:
@@ -2108,27 +2708,30 @@ 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.
     #
     # The server's capabilities must include +CONDSTORE+
-    # {[RFC7162]}[https://tools.ietf.org/html/rfc7162] in order to use the
+    # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162] in order to use the
     # +unchangedsince+ argument.  Using +unchangedsince+ implicitly enables the
     # +CONDSTORE+ extension.
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled, the
+    # +STORE+ command is prohibited.  Use #uid_store instead.
     def store(set, attr, flags, unchangedsince: nil)
       store_internal("STORE", set, attr, flags, unchangedsince: unchangedsince)
     end
 
     # :call-seq:
-    #   uid_store(set, attr, value, unchangedsince: nil) -> array of FetchData
+    #   uid_store(set, attr, value, unchangedsince: nil) -> array of FetchData (or UIDFetchData)
     #
     # Sends a {UID STORE command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
     # to alter data associated with messages in the mailbox, in particular their
@@ -2139,8 +2742,13 @@ module Net
     #
     # Related: #store
     #
-    # ===== Capabilities
-    # Same as #store.
+    # ==== Capabilities
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled,
+    # #uid_store must be used instead of #store, and UIDFetchData will be
+    # returned instead of FetchData.
+    #
+    # Otherwise, #uid_store is updated by extensions in the same way as #store.
     def uid_store(set, attr, flags, unchangedsince: nil)
       store_internal("UID STORE", set, attr, flags, unchangedsince: unchangedsince)
     end
@@ -2152,13 +2760,16 @@ 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
     # with UIDPlusData.  This will report the UIDVALIDITY of the destination
     # mailbox, the UID set of the source messages, and the assigned UID set of
     # the moved messages.
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled, the
+    # +COPY+ command is prohibited.  Use #uid_copy instead.
     def copy(set, mailbox)
       copy_internal("COPY", set, mailbox)
     end
@@ -2169,9 +2780,12 @@ module Net
     #
     # Similar to #copy, but +set+ contains unique identifiers.
     #
-    # ===== Capabilities
+    # ==== Capabilities
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] in enabled,
+    # #uid_copy must be used instead of #copy.
     #
-    # +UIDPLUS+ affects #uid_copy the same way it affects #copy.
+    # Otherwise, #uid_copy is updated by extensions in the same way as #copy.
     def uid_copy(set, mailbox)
       copy_internal("UID COPY", set, mailbox)
     end
@@ -2184,10 +2798,10 @@ module Net
     #
     # Related: #uid_move
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
-    # The server's capabilities must include +MOVE+
-    # [RFC6851[https://tools.ietf.org/html/rfc6851]].
+    # The server's capabilities must include either +IMAP4rev2+ or +MOVE+
+    # [RFC6851[https://www.rfc-editor.org/rfc/rfc6851]].
     #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
     # supported, the server's response should include a +COPYUID+ response code
@@ -2195,6 +2809,8 @@ module Net
     # mailbox, the UID set of the source messages, and the assigned UID set of
     # the moved messages.
     #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled, the
+    # +MOVE+ command is prohibited.  Use #uid_move instead.
     def move(set, mailbox)
       copy_internal("MOVE", set, mailbox)
     end
@@ -2208,11 +2824,15 @@ module Net
     #
     # Related: #move
     #
-    # ===== Capabilities
+    # ==== Capabilities
+    #
+    # The server's capabilities must include either +IMAP4rev2+ or +MOVE+
+    # [RFC6851[https://www.rfc-editor.org/rfc/rfc6851]].
+    #
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] is enabled,
+    # #uid_move must be used instead of #move.
     #
-    # Same as #move: The server's capabilities must include +MOVE+
-    # [RFC6851[https://tools.ietf.org/html/rfc6851]].  +UIDPLUS+ also affects
-    # #uid_move the same way it affects #move.
+    # Otherwise, #uid_move is updated by extensions in the same way as #move.
     def uid_move(set, mailbox)
       copy_internal("UID MOVE", set, mailbox)
     end
@@ -2228,17 +2848,17 @@ 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]].
+    # [RFC5256[https://www.rfc-editor.org/rfc/rfc5256]].
     def sort(sort_keys, search_keys, charset)
       return sort_internal("SORT", sort_keys, search_keys, charset)
     end
@@ -2250,10 +2870,10 @@ 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]].
+    # [RFC5256[https://www.rfc-editor.org/rfc/rfc5256]].
     def uid_sort(sort_keys, search_keys, charset)
       return sort_internal("UID SORT", sort_keys, search_keys, charset)
     end
@@ -2275,10 +2895,10 @@ 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]].
+    # [RFC5256[https://www.rfc-editor.org/rfc/rfc5256]].
     def thread(algorithm, search_keys, charset)
       return thread_internal("THREAD", algorithm, search_keys, charset)
     end
@@ -2289,10 +2909,10 @@ 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]].
+    # [RFC5256[https://www.rfc-editor.org/rfc/rfc5256]].
     def uid_thread(algorithm, search_keys, charset)
       return thread_internal("UID THREAD", algorithm, search_keys, charset)
     end
@@ -2308,11 +2928,11 @@ module Net
     #
     # Related: #capable?, #capabilities, #capability
     #
-    # ===== Capabilities
+    # ==== Capabilities
     #
     # The server's capabilities must include
-    # +ENABLE+ [RFC5161[https://tools.ietf.org/html/rfc5161]]
-    # or +IMAP4REV2+ [RFC9051[https://tools.ietf.org/html/rfc9051]].
+    # +ENABLE+ [RFC5161[https://www.rfc-editor.org/rfc/rfc5161]]
+    # or +IMAP4REV2+ [RFC9051[https://www.rfc-editor.org/rfc/rfc9051]].
     #
     # Additionally, the server capabilities must include a capability matching
     # each enabled extension (usually the same name as the enabled extension).
@@ -2331,7 +2951,7 @@ module Net
     #   <tt>"UTF8=ACCEPT"</tt> or <tt>"IMAP4rev2"</tt>, depending on server
     #   capabilities.
     #
-    # [<tt>"UTF8=ACCEPT"</tt> [RFC6855[https://tools.ietf.org/html/rfc6855]]]
+    # [<tt>"UTF8=ACCEPT"</tt> [RFC6855[https://www.rfc-editor.org/rfc/rfc6855]]]
     #
     #   The server's capabilities must include <tt>UTF8=ACCEPT</tt> _or_
     #   <tt>UTF8=ONLY</tt>.
@@ -2350,13 +2970,23 @@ module Net
     #   encoding, even if they generally contain UTF-8 data, if they are
     #   text at all.
     #
-    # [<tt>"UTF8=ONLY"</tt> [RFC6855[https://tools.ietf.org/html/rfc6855]]]
+    # [<tt>"UTF8=ONLY"</tt> [RFC6855[https://www.rfc-editor.org/rfc/rfc6855]]]
     #
     #   A server that reports the <tt>UTF8=ONLY</tt> capability _requires_ that
     #   the client <tt>enable("UTF8=ACCEPT")</tt> before any mailboxes may be
     #   selected.  For convenience, <tt>enable("UTF8=ONLY")</tt> is aliased to
     #   <tt>enable("UTF8=ACCEPT")</tt>.
     #
+    # [+UIDONLY+ {[RFC9586]}[https://www.rfc-editor.org/rfc/rfc9586.pdf]]
+    #
+    #   When UIDONLY is enabled, the #fetch, #store, #search, #copy, and #move
+    #   commands are prohibited and result in a tagged BAD response. Clients
+    #   should instead use uid_fetch, uid_store, uid_search, uid_copy, or
+    #   uid_move, respectively. All +FETCH+ responses that would be returned are
+    #   replaced by +UIDFETCH+ responses. All +EXPUNGED+ responses that would be
+    #   returned are replaced by +VANISHED+ responses. The "<sequence set>"
+    #   uid_search criterion is prohibited.
+    #
     # ===== Unsupported capabilities
     #
     # *Note:* Some extensions that use ENABLE permit the server to send syntax
@@ -2397,17 +3027,23 @@ 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
+    # ==== Capabilities
     #
-    # The server's capabilities must include +IDLE+
-    # [RFC2177[https://tools.ietf.org/html/rfc2177]].
+    # The server's capabilities must include either +IMAP4rev2+ or +IDLE+
+    # [RFC2177[https://www.rfc-editor.org/rfc/rfc2177]].
     def idle(timeout = nil, &response_handler)
       raise LocalJumpError, "no block given" unless response_handler
 
@@ -2429,7 +3065,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 +3073,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 +3089,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.
     #
-    # 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.
+    # [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>
+    #
+    #     [+: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 +3191,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 +3224,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 +3238,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.
@@ -2559,6 +3291,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
@@ -2582,13 +3318,13 @@ 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
+      @response_handlers.each do |handler| handler.call(@greeting) end
       @receiver_thread = start_receiver_thread
     rescue Exception
+      state_logout!
       @sock.close
       raise
     end
@@ -2597,7 +3333,10 @@ module Net
       greeting = get_response
       raise Error, "No server greeting - connection closed" unless greeting
       record_untagged_response_code greeting
-      raise ByeResponseError, greeting if greeting.name == "BYE"
+      case greeting.name
+      when "PREAUTH" then state_authenticated!
+      when "BYE"     then state_logout!; raise ByeResponseError, greeting
+      end
       greeting
     end
 
@@ -2607,16 +3346,18 @@ module Net
       rescue Exception => ex
         @receiver_thread_exception = ex
         # don't exit the thread with an exception
+      ensure
+        state_logout!
       end
     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
@@ -2629,6 +3370,7 @@ module Net
           resp = get_response
         rescue Exception => e
           synchronize do
+            state_logout!
             @sock.close
             @exception = e
           end
@@ -2648,6 +3390,7 @@ module Net
               @tagged_response_arrival.broadcast
               case resp.tag
               when @logout_command_tag
+                state_logout!
                 return
               when @continued_command_tag
                 @continuation_request_exception =
@@ -2657,6 +3400,7 @@ module Net
             when UntaggedResponse
               record_untagged_response(resp)
               if resp.name == "BYE" && @logout_command_tag.nil?
+                state_logout!
                 @sock.close
                 @exception = ByeResponseError.new(resp)
                 connection_closed = true
@@ -2664,6 +3408,7 @@ module Net
             when ContinuationRequest
               @continuation_request_arrival.signal
             end
+            state_unselected! if resp in {data: {code: {name: "CLOSED"}}}
             @response_handlers.each do |handler|
               handler.call(resp)
             end
@@ -2715,23 +3460,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 @@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
 
     #############################
@@ -2807,7 +3539,7 @@ module Net
 
     def put_string(str)
       @sock.print(str)
-      if @@debug
+      if config.debug?
         if @debug_output_bol
           $stderr.print("C: ")
         end
@@ -2820,23 +3552,115 @@ 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 expunge_internal(...)
+      synchronize do
+        send_command(...)
+        expunged_array = clear_responses("EXPUNGE")
+        vanished_array = extract_responses("VANISHED") { !_1.earlier? }
+        if vanished_array.empty?
+          expunged_array
+        elsif vanished_array.length == 1
+          vanished_array.first
+        else
+          merged_uids = SequenceSet[*vanished_array.map(&:uids)]
+          VanishedData[uids: merged_uids, earlier: false]
+        end
+      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 PartialRange::Negative then PartialRange[opt]
+        when Range                  then SequenceSet[opt]
+        else                             opt
+        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
 
-    def fetch_internal(cmd, set, attr, mod = nil, changedsince: nil)
+    def fetch_internal(cmd, set, attr, mod = nil, partial: nil, changedsince: nil)
+      set = SequenceSet[set]
+      if partial
+        mod ||= []
+        mod << "PARTIAL" << PartialRange[partial]
+      end
       if changedsince
         mod ||= []
         mod << "CHANGEDSINCE" << Integer(changedsince)
@@ -2850,39 +3674,36 @@ module Net
         }
       end
 
-      synchronize do
-        clear_responses("FETCH")
-        if mod
-          send_command(cmd, MessageSet.new(set), attr, mod)
-        else
-          send_command(cmd, MessageSet.new(set), attr)
-        end
-        clear_responses("FETCH")
-      end
+      args = [cmd, set, attr]
+      args << mod if mod
+      send_command_returning_fetch_results(*args)
     end
 
     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
+      send_command_returning_fetch_results(cmd, *args)
+    end
+
+    def send_command_returning_fetch_results(...)
       synchronize do
         clear_responses("FETCH")
-        send_command(cmd, *args)
-        clear_responses("FETCH")
+        clear_responses("UIDFETCH")
+        send_command(...)
+        fetches    = clear_responses("FETCH")
+        uidfetches = clear_responses("UIDFETCH")
+        uidfetches.any? ? uidfetches : fetches
       end
     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 +3711,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
 
@@ -2932,15 +3767,39 @@ 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)
+      ssl_socket_connect(@sock, open_timeout)
       if ssl_ctx.verify_mode != VERIFY_NONE
         @sock.post_connection_check(@host)
         @tls_verified = true
       end
     end
 
+    def state_authenticated!(resp = nil)
+      synchronize do
+        @capabilities = capabilities_from_resp_code resp if resp
+        @connection_state = ConnectionState::Authenticated.new
+      end
+    end
+
+    def state_selected!
+      synchronize do
+        @connection_state = ConnectionState::Selected.new
+      end
+    end
+
+    def state_unselected!
+      state_authenticated! if connection_state.to_sym == :selected
+    end
+
+    def state_logout!
+      synchronize do
+        @connection_state = ConnectionState::Logout.new
+      end
+    end
+
     def sasl_adapter
       SASLAdapter.new(self, &method(:send_command_with_continuations))
     end
@@ -2959,8 +3818,10 @@ module Net
 end
 
 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"