net-imap 0.5.9 → 0.6.4

data/lib/net/imap.rb

@@ -359,8 +359,8 @@ module Net
   #
   # - #capability: Returns the server's capabilities as an array of strings.
   #
-  #   <em>In general, #capable? should be used rather than explicitly sending a
-  #   +CAPABILITY+ command to the server.</em>
+  #   <em>In general,</em> #capable? <em>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.
   #
@@ -450,8 +450,8 @@ module Net
   #
   # 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+.
+  # +ENABLE+, +IDLE+, +LITERAL-+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+,
+  # +UNSELECT+, <tt>STATUS=SIZE</tt>, and the fetch side of +BINARY+.
   # Commands for these extensions are listed with the {Core IMAP
   # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.
   #
@@ -459,9 +459,12 @@ module Net
   #   <em>The following are folded into +IMAP4rev2+ but are currently
   #   unsupported or incompletely supported by</em> Net::IMAP<em>: RFC4466
   #   extensions, +SEARCHRES+, +LIST-EXTENDED+, +LIST-STATUS+,
-  #   +LITERAL-+, and +SPECIAL-USE+.</em>
+  #   and +SPECIAL-USE+.</em>
   #
   # ==== RFC2087: +QUOTA+
+  # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
+  # - Obsoleted by <tt>QUOTA=RES-*</tt> [RFC9208[https://www.rfc-editor.org/rfc/rfc9208]],
+  #   although the commands are backward compatible.
   # - #getquota: returns the resource usage and limits for a quota root
   # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
   #   their resource usage and limits.
@@ -486,9 +489,7 @@ module Net
   # 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.
-  #
-  # >>>
-  #   *NOTE:* The binary extension the #append command is _not_ supported yet.
+  # - Updates #append to allow binary messages containing +NULL+ bytes.
   #
   # ==== RFC3691: +UNSELECT+
   # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
@@ -568,6 +569,15 @@ module Net
   # - Updates #store and #uid_store with the +unchangedsince+ modifier and adds
   #   the +MODIFIED+ ResponseCode to the tagged response.
   #
+  # ==== RFC7888: <tt>LITERAL+</tt>
+  # - Literal strings smaller than Config#max_non_synchronizing_literal bytes
+  #   are sent without waiting for the server's continuation request.
+  #
+  # ==== RFC7888: +LITERAL-+
+  # - Literal strings smaller than 4096 bytes or
+  #   Config#max_non_synchronizing_literal (whichever is smaller)
+  #   are sent without waiting for the server's continuation request.
+  #
   # ==== RFC8438: <tt>STATUS=SIZE</tt>
   # - Updates #status with the +SIZE+ status attribute.
   #
@@ -578,6 +588,16 @@ module Net
   #   See FetchData#emailid and FetchData#emailid.
   # - Updates #status with support for the +MAILBOXID+ status attribute.
   #
+  # ==== RFC9208: <tt>QUOTA=RES-*</tt>
+  # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
+  # - Obsoletes the +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+  #   extension and provides strict semantics for different resource types.
+  # - #getquota: returns the resource usage and limits for a quota root
+  # - #getquotaroot: returns the list of quota roots for a mailbox, as well as
+  #   their resource usage and limits.
+  # - #setquota: sets the resource limits for a given quota root.
+  # - Updates #status with <tt>"DELETED"</tt> and +DELETED-STORAGE+ attributes.
+  #
   # ==== RFC9394: +PARTIAL+
   # - Updates #search, #uid_search with the +PARTIAL+ return option which adds
   #   ESearchResult#partial return data.
@@ -631,9 +651,9 @@ module Net
   #   RFC 5322, DOI 10.17487/RFC5322, October 2008,
   #   <https://www.rfc-editor.org/info/rfc5322>.
   #
-  #   <em>Note: obsoletes</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>
+  #   *NOTE*: obsoletes
+  #   RFC-2822[https://www.rfc-editor.org/rfc/rfc2822] (April 2001) and
+  #   RFC-822[https://www.rfc-editor.org/rfc/rfc822] (August 1982).
   #
   # [CHARSET[https://www.rfc-editor.org/rfc/rfc2978]]::
   #   Freed, N. and J. Postel, "IANA Charset Registration Procedures", BCP 19,
@@ -698,13 +718,12 @@ module Net
   #
   # === \IMAP Extensions
   #
-  # [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>.
+  # [QUOTA[https://www.rfc-editor.org/rfc/rfc2087]]::
+  #   Myers, J., "IMAP4 QUOTA extension", RFC 2087, DOI 10.17487/RFC2087,
+  #   January 1997, <https://www.rfc-editor.org/info/rfc2087>.
   #
-  #   <em>Note: obsoletes</em>
-  #   RFC-2087[https://www.rfc-editor.org/rfc/rfc2087]<em> (January 1997)</em>.
-  #   <em>Net::IMAP does not fully support the RFC9208 updates yet.</em>
+  #   *NOTE*: _obsoleted_ by RFC9208[https://www.rfc-editor.org/rfc/rfc9208]
+  #   (March 2022).
   # [IDLE[https://www.rfc-editor.org/rfc/rfc2177]]::
   #   Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177,
   #   June 1997, <https://www.rfc-editor.org/info/rfc2177>.
@@ -741,8 +760,8 @@ module Net
   #   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://www.rfc-editor.org/rfc/rfc6855]]::
-  # [UTF8=ONLY[https://www.rfc-editor.org/rfc/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>.
@@ -756,6 +775,11 @@ module Net
   #   Gondwana, B., Ed., "IMAP Extension for Object Identifiers",
   #   RFC 8474, DOI 10.17487/RFC8474, September 2018,
   #   <https://www.rfc-editor.org/info/rfc8474>.
+  # [{QUOTA=RES-*}[https://www.rfc-editor.org/rfc/rfc9208]]::
+  #   Melnikov, A., "IMAP QUOTA Extension", RFC 9208, DOI 10.17487/RFC9208,
+  #   March 2022, <https://www.rfc-editor.org/info/rfc9208>.
+  #
+  #   Obsoletes RFC2087[https://www.rfc-editor.org/rfc/rfc2087].
   # [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,
@@ -769,6 +793,7 @@ module Net
   #
   # === IANA registries
   # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
+  #   * {IMAP Quota Resource Types}[http://www.iana.org/assignments/imap4-capabilities#imap-capabilities-2]
   # * {IMAP Response Codes}[https://www.iana.org/assignments/imap-response-codes/imap-response-codes.xhtml]
   # * {IMAP Mailbox Name Attributes}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml]
   # * {IMAP and JMAP Keywords}[https://www.iana.org/assignments/imap-jmap-keywords/imap-jmap-keywords.xhtml]
@@ -779,8 +804,8 @@ 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:
-  # * {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]
   # * {IMAP ANNOTATE Extension Entries and Attributes}[https://www.iana.org/assignments/imap-annotate-extension/imap-annotate-extension.xhtml]
@@ -788,7 +813,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.9"
+    VERSION = "0.6.4"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -805,10 +830,6 @@ module Net
     autoload :StringPrep,             "#{dir}/stringprep"
 
     include MonitorMixin
-    if defined?(OpenSSL::SSL)
-      include OpenSSL
-      include SSL
-    end
 
     # :call-seq:
     #   Net::IMAP::SequenceSet(set = nil) -> SequenceSet
@@ -1124,6 +1145,31 @@ module Net
       start_imap_connection
     end
 
+    # Returns a string representation of +self+, showing basic client state
+    # information.
+    #
+    #   imap = Net::IMAP.new(hostname, ssl: true)
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS not_authenticated>"
+    #
+    #   imap.authenticate(:oauthbearer, "user", token)
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS authenticated>"
+    #
+    #   imap.select("INBOX")
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS selected>"
+    #
+    #   imap.logout
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS logout>"
+    #
+    def inspect
+      tls_state = tls_verified? ? "TLS" :
+        ssl_ctx ? "TLS (NOT VERIFIED)" :
+        "PLAINTEXT"
+      conn_state = disconnected? ? "disconnected" : connection_state.to_sym
+      "#<%s:0x%08x %s:%s %s %s>" % [
+        self.class.name, __id__, host, port, tls_state, conn_state
+      ]
+    end
+
     # Returns true after the TLS negotiation has completed and the remote
     # hostname has been verified.  Returns false when TLS has been established
     # but peer verification was disabled.
@@ -1394,9 +1440,11 @@ module Net
     #
     def starttls(**options)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options)
+      handled = false
       error = nil
       ok = send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
+          handled = true
           clear_cached_capabilities
           clear_responses
           start_tls_session
@@ -1408,6 +1456,13 @@ module Net
         disconnect
         raise error
       end
+      unless handled
+        disconnect
+        raise InvalidResponseError,
+              "STARTTLS handler was bypassed, although server responded %p" % [
+                ok.raw_data.chomp
+              ]
+      end
       ok
     end
 
@@ -1522,6 +1577,7 @@ module Net
     # completes.  If the TaggedResponse to #authenticate includes updated
     # capabilities, they will be cached.
     def authenticate(*args, sasl_ir: config.sasl_ir, **props, &callback)
+      sasl_ir = may_depend_on_capabilities_cached?(sasl_ir)
       sasl_adapter.authenticate(*args, sasl_ir: sasl_ir, **props, &callback)
         .tap do state_authenticated! _1 end
     end
@@ -1573,7 +1629,7 @@ module Net
     # When the +condstore+ keyword argument is true, the server is told to
     # enable the extension.  If +mailbox+ supports persistence of mod-sequences,
     # the +HIGHESTMODSEQ+ ResponseCode will be sent as an untagged response to
-    # #select and all `FETCH` responses will include FetchData#modseq.
+    # #select and all +FETCH+ responses will include FetchData#modseq.
     # Otherwise, the +NOMODSEQ+ ResponseCode will be sent.
     #
     # A Net::IMAP::NoResponseError is raised if the mailbox does not
@@ -1828,12 +1884,18 @@ module Net
     # to both admin and user.  If this mailbox exists, it returns an array
     # containing objects of type MailboxQuotaRoot and MailboxQuota.
     #
+    # *NOTE:* Currently, Net::IMAP only supports +QUOTA+ responses with a single
+    # resource type.  This is usually +STORAGE+, but you may need to verify this
+    # with UntaggedResponse#raw_data.
+    #
     # Related: #getquota, #setquota, MailboxQuotaRoot, MailboxQuota
     #
     # ==== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]].
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
     def getquotaroot(mailbox)
       synchronize do
         send_command("GETQUOTAROOT", mailbox)
@@ -1845,41 +1907,59 @@ module Net
     end
 
     # Sends a {GETQUOTA command [RFC2087 §4.2]}[https://www.rfc-editor.org/rfc/rfc2087#section-4.2]
-    # along with specified +mailbox+.  If this mailbox exists, then an array
-    # containing a MailboxQuota object is returned.  This command is generally
-    # only available to server admin.
+    # for the +quota_root+.  If this quota root exists, then an array
+    # containing a MailboxQuota object is returned.
+    #
+    # The names of quota roots that are applicable to a particular mailbox can
+    # be discovered with #getquotaroot.
+    #
+    # *NOTE:* Currently, Net::IMAP only supports +QUOTA+ responses with a single
+    # resource type.  This is usually +STORAGE+, but you may need to verify this
+    # with UntaggedResponse#raw_data.
     #
     # Related: #getquotaroot, #setquota, MailboxQuota
     #
     # ==== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]].
-    def getquota(mailbox)
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
+    def getquota(quota_root)
       synchronize do
-        send_command("GETQUOTA", mailbox)
+        send_command("GETQUOTA", quota_root)
         clear_responses("QUOTA")
       end
     end
 
     # Sends a {SETQUOTA command [RFC2087 §4.1]}[https://www.rfc-editor.org/rfc/rfc2087#section-4.1]
-    # along with the specified +mailbox+ and +quota+.  If +quota+ is nil, then
-    # +quota+ will be unset for that mailbox.  Typically one needs to be logged
-    # in as a server admin for this to work.
+    # along with the specified +quota_root+ and +storage_limit+.  If
+    # +storage_limit+ is +nil+, resource limits are unset for that quota root.
+    # If +storage_limit+ is a number, it sets the +STORAGE+ resource limit.
+    #
+    #   imap.setquota "#user/alice", 100
+    #   imap.getquota "#user/alice"
+    #   # => [#<struct Net::IMAP::MailboxQuota mailbox="#user/alice" usage=54 quota=100>]
+    #
+    # Typically one needs to be logged in as a server admin for this to work.
+    #
+    # *NOTE:* Currently, Net::IMAP only supports setting +STORAGE+ quota limits.
     #
     # Related: #getquota, #getquotaroot
     #
     # ==== Capabilities
     #
-    # The server's capabilities must include +QUOTA+
-    # [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]].
-    def setquota(mailbox, quota)
-      if quota.nil?
-        data = '()'
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # capability, or a capability prefixed with <tt>QUOTA=RES-*</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208] for each supported
+    # resource type.
+    def setquota(quota_root, storage_limit)
+      if storage_limit.nil?
+        list = []
       else
-        data = '(STORAGE ' + quota.to_s + ')'
+        list = ["STORAGE", NumValidator.coerce_number64(storage_limit)]
       end
-      send_command("SETQUOTA", mailbox, RawData.new(data))
+      send_command("SETQUOTA", quota_root, list)
     end
 
     # Sends a {SETACL command [RFC4314 §3.1]}[https://www.rfc-editor.org/rfc/rfc4314#section-3.1]
@@ -1986,7 +2066,10 @@ module Net
     # <tt>STATUS=SIZE</tt>
     # {[RFC8483]}[https://www.rfc-editor.org/rfc/rfc8483.html].
     #
-    # +DELETED+ requires the server's capabilities to include +IMAP4rev2+.
+    # +DELETED+ must be supported when the server's capabilities includes
+    # +IMAP4rev2+.
+    # or <tt>QUOTA=RES-MESSAGES</tt>
+    # {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208.html].
     #
     # +HIGHESTMODSEQ+ requires the server's capabilities to include +CONDSTORE+
     # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
@@ -2022,9 +2105,14 @@ module Net
     #
     # ==== Capabilities
     #
+    # If +BINARY+ [RFC3516[https://www.rfc-editor.org/rfc/rfc3516.html]] is
+    # supported by the server, +message+ may contain +NULL+ characters and
+    # be sent as a binary literal.  Otherwise, binary message parts must be
+    # encoded appropriately (for example, +base64+).
+    #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
     # supported and the destination supports persistent UIDs, the server's
-    # response should include an +APPENDUID+ response code with UIDPlusData.
+    # response should include an +APPENDUID+ response code with AppendUIDData.
     # This will report the UIDVALIDITY of the destination mailbox and the
     # assigned UID of the appended message.
     #
@@ -2032,12 +2120,11 @@ module Net
     # TODO: add MULTIAPPEND support
     #++
     def append(mailbox, message, flags = nil, date_time = nil)
+      message = StringFormatter.literal_or_literal8(message, name: "message")
       args = []
-      if flags
-        args.push(flags)
-      end
+      args.push(flags)     if flags
       args.push(date_time) if date_time
-      args.push(Literal.new(message))
+      args.push(message)
       send_command("APPEND", mailbox, *args)
     end
 
@@ -2110,8 +2197,8 @@ module Net
     end
 
     # call-seq:
-    #   uid_expunge{uid_set) -> array of message sequence numbers
-    #   uid_expunge{uid_set) -> VanishedData of UIDs
+    #   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]
@@ -2267,11 +2354,11 @@ module Net
     #     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>.
+    #   +criteria+ will be sent to the server <em>with minimal validation and no
+    #   encoding or formatting</em>.
     #
-    #   <em>*WARNING:* This is vulnerable to injection attacks when external
-    #   inputs are used.</em>
+    #   <em>*WARNING:* Although CRLF is prohibited, this is vulnerable to other
+    #   types of attribute injection attack if unvetted user input is used.</em>
     #
     # ==== Supported return options
     #
@@ -2592,6 +2679,13 @@ module Net
     #
     # +attr+ is a list of attributes to fetch; see FetchStruct documentation for
     # a list of supported attributes.
+    # >>>
+    #   When +attr+ is a String, it will be sent <em>with minimal validation and
+    #   no encoding or formatting</em>.  When +attr+ is an Array, each String in
+    #   +attr+ will be sent this way.
+    #
+    #   <em>*WARNING:* Although CRLF is prohibited, this is vulnerable to other
+    #   types of attribute injection attack if unvetted user input is used.</em>
     #
     # +changedsince+ is an optional integer mod-sequence.  It limits results to
     # messages with a mod-sequence greater than +changedsince+.
@@ -2675,6 +2769,7 @@ module Net
     #     # fetch should return quickly and allocate little memory
     #     results.size # => 0..500
     #     break if results.empty?
+    #     results.sort_by!(&:uid) # server may return results out of order
     #     next_uid_to_fetch = results.last.uid + 1
     #     process results
     #   end
@@ -2780,7 +2875,7 @@ module Net
     #
     # 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
+    # with CopyUIDData.  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.
     #
@@ -2821,7 +2916,7 @@ module Net
     #
     # 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
+    # with CopyUIDData.  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.
     #
@@ -2961,6 +3056,18 @@ module Net
     #   command parameters defined by the extension will implicitly enable it.
     #   See {[RFC7162 §3.1]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1].
     #
+    # [+QRESYNC+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html]]
+    #   *NOTE:* Enabling QRESYNC will replace +EXPUNGE+ with +VANISHED+, but
+    #   the extension arguments to #select, #examine, and #uid_fetch are not
+    #   supported yet.
+    #
+    #   Adds quick resynchronization options to #select, #examine, and
+    #   #uid_fetch.  +QRESYNC+ _must_ be explicitly enabled before using any of
+    #   the extension's command parameters.  All +EXPUNGE+ responses will be
+    #   replaced with +VANISHED+ responses.  Enabling +QRESYNC+ implicitly
+    #   enables +CONDSTORE+ as well.
+    #   See {[RFC7162 §3.2]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.2].
+    #
     # [+:utf8+ --- an alias for <tt>"UTF8=ACCEPT"</tt>]
     #
     #   In a future release, <tt>enable(:utf8)</tt> will enable either
@@ -3067,6 +3174,7 @@ module Net
 
       synchronize do
         tag = Thread.current[:net_imap_tag] = generate_tag
+        guard_against_tagged_response_skipping_handler!(tag, "IDLE")
         put_string("#{tag} IDLE#{CRLF}")
 
         begin
@@ -3220,7 +3328,7 @@ module Net
           warn(RESPONSES_DEPRECATION_MSG, uplevel: 1, category: :deprecated)
         when :frozen_dup
           synchronize {
-            responses = @responses.transform_values(&:freeze)
+            responses = @responses.transform_values { _1.dup.freeze }
             responses.default_proc = nil
             responses.default = [].freeze
             return responses.freeze
@@ -3471,7 +3579,7 @@ module Net
         raise BadResponseError, resp
       else
         disconnect
-        raise InvalidResponseError, "invalid tagged resp: %p" % [resp.raw.chomp]
+        raise InvalidResponseError, "invalid tagged resp: %p" % [resp.raw_data.chomp]
       end
     end
 
@@ -3531,21 +3639,29 @@ module Net
           put_string(" ")
           send_data(i, tag)
         end
-        put_string(CRLF)
-        if cmd == "LOGOUT"
-          @logout_command_tag = tag
-        end
-        if block
-          add_response_handler(&block)
-        end
+        @logout_command_tag = tag if cmd == "LOGOUT"
+        guard_against_tagged_response_skipping_handler!(tag, cmd)
+        add_response_handler(&block) if block
         begin
-          return get_tagged_response(tag, cmd)
+          put_string(CRLF)
+          get_tagged_response(tag, cmd)
         ensure
-          if block
-            remove_response_handler(block)
-          end
+          remove_response_handler(block) if block
         end
       end
+    rescue InvalidResponseError
+      disconnect
+      raise
+    end
+
+    def guard_against_tagged_response_skipping_handler!(tag, cmd)
+      return unless (resp = @tagged_responses[tag])&.name&.upcase == "OK"
+      raise InvalidResponseError, format(
+        "Received tagged 'OK' to incomplete %s command (tag=%s).  " \
+        "This could indicate a malicious server, a man-in-the-middle, or " \
+        "client-side command injection.  Disconnecting.",
+        cmd, tag
+      )
     end
 
     def generate_tag
@@ -3569,11 +3685,11 @@ module Net
     end
 
     def enforce_logindisabled?
-      if config.enforce_logindisabled == :when_capabilities_cached
-        capabilities_cached?
-      else
-        config.enforce_logindisabled
-      end
+      may_depend_on_capabilities_cached?(config.enforce_logindisabled)
+    end
+
+    def may_depend_on_capabilities_cached?(value)
+      value == :when_capabilities_cached ? capabilities_cached? : value
     end
 
     def expunge_internal(...)
@@ -3672,6 +3788,9 @@ module Net
     end
 
     def fetch_internal(cmd, set, attr, mod = nil, partial: nil, changedsince: nil)
+      if partial && !cmd.start_with?("UID ")
+        raise ArgumentError, "partial can only be used with uid_fetch"
+      end
       set = SequenceSet[set]
       if partial
         mod ||= []
@@ -3696,7 +3815,7 @@ module Net
     end
 
     def store_internal(cmd, set, attr, flags, unchangedsince: nil)
-      attr = RawData.new(attr) if attr.instance_of?(String)
+      attr = Atom.new(attr) if attr.instance_of?(String)
       args = [SequenceSet.new(set)]
       args << ["UNCHANGEDSINCE", Integer(unchangedsince)] if unchangedsince
       args << attr << flags
@@ -3766,12 +3885,9 @@ module Net
     def build_ssl_ctx(ssl)
       if ssl
         params = (Hash.try_convert(ssl) || {}).freeze
-        context = SSLContext.new
+        context = OpenSSL::SSL::SSLContext.new
         context.set_params(params)
-        if defined?(VerifyCallbackProc)
-          context.verify_callback = VerifyCallbackProc
-        end
-        context.freeze
+        context.setup
         [params, context]
       else
         false
@@ -3782,12 +3898,12 @@ module Net
       raise "SSL extension not installed" unless defined?(OpenSSL::SSL)
       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)
+      @sock = OpenSSL::SSL::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)
-      if ssl_ctx.verify_mode != VERIFY_NONE
+      if ssl_ctx.verify_mode != OpenSSL::SSL::VERIFY_NONE
         @sock.post_connection_check(@host)
         @tls_verified = true
       end
@@ -3851,7 +3967,6 @@ 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"

data/net-imap.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{Ruby client api for Internet Message Access Protocol}
   spec.description   = %q{Ruby client api for Internet Message Access Protocol}
   spec.homepage      = "https://github.com/ruby/net-imap"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
   spec.licenses       = ["Ruby", "BSD-2-Clause"]
 
   spec.metadata["homepage_uri"] = spec.homepage

data/rakelib/rdoc.rake

@@ -12,17 +12,6 @@ module RDoc::Generator
       end
     end
 
-    # See https://github.com/ruby/rdoc/pull/936
-    module FixSectionComments
-      def markup(text)
-        @store ||= @parent&.store
-        super
-      end
-      def description; markup comment end
-      def comment;     super || @comments&.first end
-      def parse(_comment_location = nil) super() end
-    end
-
     # render "[label] data" lists as tables.  adapted from "hanna-nouveau" gem.
     module LabelListTable
       def list_item_start(list_item, list_type)
@@ -51,20 +40,14 @@ class RDoc::AnyMethod
   prepend RDoc::Generator::NetIMAP::RemoveRedundantParens
 end
 
-class RDoc::Context::Section
-  prepend RDoc::Generator::NetIMAP::FixSectionComments
-end
-
 class RDoc::Markup::ToHtml
   LIST_TYPE_TO_HTML[:NOTE] = ['<table class="rdoc-list note-list"><tbody>', '</tbody></table>']
   prepend RDoc::Generator::NetIMAP::LabelListTable
 end
 
 RDoc::Task.new do |doc|
-  doc.main       = "README.md"
   doc.title      = "net-imap #{Net::IMAP::VERSION}"
   doc.rdoc_dir   = "doc"
-  doc.rdoc_files = FileList.new %w[lib/**/*.rb *.rdoc *.md]
   doc.options << "--template-stylesheets" << "docs/styles.css"
-  # doc.generator  = "hanna"
+  doc.generator  = "darkfish" # TODO: fix issues with aliki
 end