net-imap 0.5.4 → 0.5.6

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
   #
@@ -299,15 +299,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
@@ -404,7 +404,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+.
@@ -424,13 +424,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.
   #
@@ -439,7 +439,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.
   #
@@ -447,7 +447,7 @@ 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,
   #   without expunging any messages.
@@ -459,7 +459,7 @@ 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
@@ -467,15 +467,15 @@ module Net
   # - Updates #copy, #move with the +COPYUID+ ResponseCode
   #
   # ==== RFC4731: +ESEARCH+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
+  # 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.
   #
@@ -499,7 +499,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.
@@ -539,6 +539,12 @@ module Net
   #   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]]::
@@ -569,57 +575,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>.
@@ -635,12 +641,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,
@@ -648,27 +654,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>.
@@ -676,33 +682,33 @@ 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>.
@@ -711,6 +717,11 @@ module Net
   #   "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]
@@ -724,7 +735,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]
@@ -733,7 +744,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.5.4"
+    VERSION = "0.5.6"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1135,12 +1146,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
     #
     # 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))
@@ -1228,13 +1239,21 @@ 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:
@@ -1563,7 +1582,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
@@ -1592,8 +1611,8 @@ module Net
     #
     # ==== 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")
@@ -1655,7 +1674,7 @@ module Net
     # ==== 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)
@@ -1676,7 +1695,7 @@ module Net
     # ==== 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)
@@ -1694,7 +1713,7 @@ module Net
     # ==== 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 = '()'
@@ -1714,7 +1733,7 @@ module Net
     # ==== 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, "")
@@ -1732,7 +1751,7 @@ module Net
     # ==== 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)
@@ -1893,8 +1912,8 @@ module Net
     #
     # ==== 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")
     end
@@ -1921,8 +1940,8 @@ module Net
     #
     # ==== Capabilities
     #
-    # When either QRESYNC[https://tools.ietf.org/html/rfc7162] or
-    # UIDONLY[https://tools.ietf.org/html/rfc9586] are enabled, #expunge
+    # 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
@@ -2366,6 +2385,9 @@ module Net
     #   result = imap.search(["SUBJECT", "hi there", "not", "new"])
     #   #=> Net::IMAP::SearchResult[1, 6, 7, 8, modseq: 5594]
     #   result.modseq # => 5594
+    #
+    # 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
@@ -2383,6 +2405,16 @@ module Net
     # capability has been enabled.
     #
     # 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
@@ -2397,8 +2429,8 @@ module Net
     # 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+.
@@ -2427,19 +2459,22 @@ module Net
     #
     # ==== 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.
+    #
+    # 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, partial: 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.
@@ -2491,7 +2526,11 @@ module Net
     # {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394] in order to use the
     # +partial+ argument.
     #
-    # Otherwise, the same as #fetch.
+    # 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
@@ -2536,15 +2575,18 @@ module Net
     # 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
@@ -2556,7 +2598,12 @@ module Net
     # Related: #store
     #
     # ==== Capabilities
-    # Same as #store.
+    #
+    # 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
@@ -2575,6 +2622,9 @@ module Net
     # 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
@@ -2587,7 +2637,10 @@ module Net
     #
     # ==== Capabilities
     #
-    # +UIDPLUS+ affects #uid_copy the same way it affects #copy.
+    # When UIDONLY[https://www.rfc-editor.org/rfc/rfc9586.html] in enabled,
+    # #uid_copy must be used instead of #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
@@ -2602,8 +2655,8 @@ module Net
     #
     # ==== 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
@@ -2611,6 +2664,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
@@ -2626,9 +2681,13 @@ module Net
     #
     # ==== Capabilities
     #
-    # 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.
+    # 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.
+    #
+    # 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
@@ -2654,7 +2713,7 @@ module Net
     # ==== 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
@@ -2669,7 +2728,7 @@ module Net
     # ==== 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
@@ -2694,7 +2753,7 @@ module Net
     # ==== 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
@@ -2708,7 +2767,7 @@ module Net
     # ==== 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
@@ -2727,8 +2786,8 @@ module Net
     # ==== 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).
@@ -2747,7 +2806,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>.
@@ -2766,13 +2825,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
@@ -2828,8 +2897,8 @@ module Net
     #
     # ==== 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
 
@@ -3458,15 +3527,9 @@ module Net
         }
       end
 
-      synchronize do
-        clear_responses("FETCH")
-        if mod
-          send_command(cmd, set, attr, mod)
-        else
-          send_command(cmd, 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)
@@ -3474,10 +3537,17 @@ module Net
       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