net-imap 0.3.8 → 0.4.0

data/lib/net/imap.rb

@@ -24,11 +24,9 @@ end
 module Net
 
   # Net::IMAP implements Internet Message Access Protocol (\IMAP) client
-  # functionality.  The protocol is described in
-  # [IMAP4rev1[https://tools.ietf.org/html/rfc3501]].
-  #--
-  # TODO: and [IMAP4rev2[https://tools.ietf.org/html/rfc9051]].
-  #++
+  # functionality.  The protocol is described
+  # in {IMAP4rev1 [RFC3501]}[https://tools.ietf.org/html/rfc3501]
+  # and {IMAP4rev2 [RFC9051]}[https://tools.ietf.org/html/rfc9051].
   #
   # == \IMAP Overview
   #
@@ -77,31 +75,22 @@ module Net
   # UIDs have to be reassigned.  An \IMAP client thus cannot
   # rearrange message orders.
   #
-  # === Server capabilities and protocol extensions
+  # === Examples of Usage
   #
-  # Net::IMAP <em>does not modify its behavior</em> according to server
-  # #capability.  Users of the class must check for required capabilities before
-  # issuing commands.  Special care should be taken to follow all #capability
-  # requirements for #starttls, #login, and #authenticate.
-  #
-  # See the #capability method for more information.
-  #
-  # == Examples of Usage
-  #
-  # === List sender and subject of all recent messages in the default mailbox
+  # ==== List sender and subject of all recent messages in the default mailbox
   #
   #   imap = Net::IMAP.new('mail.example.com')
-  #   imap.authenticate('LOGIN', 'joe_user', 'joes_password')
+  #   imap.authenticate('PLAIN', 'joe_user', 'joes_password')
   #   imap.examine('INBOX')
   #   imap.search(["RECENT"]).each do |message_id|
   #     envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
   #     puts "#{envelope.from[0].name}: \t#{envelope.subject}"
   #   end
   #
-  # === Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
+  # ==== Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
   #
   #   imap = Net::IMAP.new('mail.example.com')
-  #   imap.authenticate('LOGIN', 'joe_user', 'joes_password')
+  #   imap.authenticate('PLAIN', 'joe_user', 'joes_password')
   #   imap.select('Mail/sent-mail')
   #   if not imap.list('Mail/', 'sent-apr03')
   #     imap.create('Mail/sent-apr03')
@@ -112,12 +101,96 @@ module Net
   #   end
   #   imap.expunge
   #
+  # == Capabilities
+  #
+  # Most Net::IMAP methods do not _currently_ modify their behaviour according
+  # to the server's advertised #capabilities.  Users of this class must check
+  # that the server is capable of extension commands or command arguments before
+  # sending them.  Special care should be taken to follow the #capabilities
+  # requirements for #starttls, #login, and #authenticate.
+  #
+  # See #capable?, #auth_capable?, #capabilities, #auth_mechanisms to discover
+  # server capabilities.  For relevant capability requirements, see the
+  # documentation on each \IMAP command.
+  #
+  #   imap = Net::IMAP.new("mail.example.com")
+  #   imap.capable?(:IMAP4rev1) or raise "Not an IMAP4rev1 server"
+  #   imap.capable?(:starttls)  or raise "Cannot start TLS"
+  #   imap.starttls
+  #
+  #   if imap.auth_capable?("PLAIN")
+  #     imap.authenticate "PLAIN", username, password
+  #   elsif !imap.capability?("LOGINDISABLED")
+  #     imap.login username, password
+  #   else
+  #     raise "No acceptable authentication mechanisms"
+  #   end
+  #
+  #   # Support for "UTF8=ACCEPT" implies support for "ENABLE"
+  #   imap.enable :utf8 if imap.auth_capable?("UTF8=ACCEPT")
+  #
+  #   namespaces  = imap.namespace if imap.capable?(:namespace)
+  #   mbox_prefix = namespaces&.personal&.first&.prefix || ""
+  #   mbox_delim  = namespaces&.personal&.first&.delim  || "/"
+  #   mbox_path   = prefix + %w[path to my mailbox].join(delim)
+  #   imap.create mbox_path
+  #
+  # === Basic IMAP4rev1 capabilities
+  #
+  # IMAP4rev1 servers must advertise +IMAP4rev1+ in their capabilities list.
+  # IMAP4rev1 servers must _implement_ the +STARTTLS+, <tt>AUTH=PLAIN</tt>,
+  # and +LOGINDISABLED+ capabilities.  See #starttls, #login, and #authenticate
+  # for the implications of these capabilities.
+  #
+  # === Caching +CAPABILITY+ responses
+  #
+  # Net::IMAP automatically stores and discards capability data according to the
+  # the requirements and recommendations in
+  # {IMAP4rev2 §6.1.1}[https://www.rfc-editor.org/rfc/rfc9051#section-6.1.1],
+  # {§6.2}[https://www.rfc-editor.org/rfc/rfc9051#section-6.2], and
+  # {§7.1}[https://www.rfc-editor.org/rfc/rfc9051#section-7.1].
+  # Use #capable?, #auth_capable?, or #capabilities to use this cache and avoid
+  # sending the #capability command unnecessarily.
+  #
+  # The server may advertise its initial capabilities using the +CAPABILITY+
+  # ResponseCode in a +PREAUTH+ or +OK+ #greeting.  When TLS has started
+  # (#starttls) and after authentication (#login or #authenticate), the server's
+  # capabilities may change and cached capabilities are discarded.  The server
+  # may send updated capabilities with an +OK+ TaggedResponse to #login or
+  # #authenticate, and these will be cached by Net::IMAP.  But the
+  # TaggedResponse to #starttls MUST be ignored--it is sent before TLS starts
+  # and is unprotected.
+  #
+  # When storing capability values to variables, be careful that they are
+  # discarded or reset appropriately, especially following #starttls.
+  #
+  # === Using IMAP4rev1 extensions
+  #
+  # See the {IANA IMAP4 capabilities
+  # registry}[http://www.iana.org/assignments/imap4-capabilities] for a list of
+  # all standard capabilities, and their reference RFCs.
+  #
+  # IMAP4rev1 servers must not activate behavior that is incompatible with the
+  # base specification until an explicit client action invokes a capability,
+  # e.g. sending a command or command argument specific to that capability.
+  # Servers may send data with backward compatible behavior, such as response
+  # codes or mailbox attributes, at any time without client action.
+  #
+  # Invoking capabilities which are unknown to Net::IMAP may cause unexpected
+  # behavior and errors.  For example, ResponseParseError is raised when
+  # unknown response syntax is received.  Invoking commands or command
+  # parameters that are unsupported by the server may raise NoResponseError,
+  # BadResponseError, or cause other unexpected behavior.
+  #
+  # Some capabilities must be explicitly activated using the #enable command.
+  # See #enable for details.
+  #
   # == Thread Safety
   #
   # Net::IMAP supports concurrent threads. For example,
   #
   #   imap = Net::IMAP.new("imap.foo.net", "imap2")
-  #   imap.authenticate("cram-md5", "bar", "password")
+  #   imap.authenticate("scram-md5", "bar", "password")
   #   imap.select("inbox")
   #   fetch_thread = Thread.start { imap.fetch(1..-1, "UID") }
   #   search_result = imap.search(["BODY", "hello"])
@@ -173,24 +246,54 @@ module Net
   # == What's here?
   #
   # * {Connection control}[rdoc-ref:Net::IMAP@Connection+control+methods]
-  # * {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands]
-  #   * {...for any state}[rdoc-ref:Net::IMAP@IMAP+commands+for+any+state]
-  #   * {...for the "not authenticated" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Not+Authenticated-22+state]
-  #   * {...for the "authenticated" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Authenticated-22+state]
-  #   * {...for the "selected" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Selected-22+state]
-  #   * {...for the "logout" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Logout-22+state]
-  # * {Supported IMAP extensions}[rdoc-ref:Net::IMAP@Supported+IMAP+extensions]
+  # * {Server capabilities}[rdoc-ref:Net::IMAP@Server+capabilities]
   # * {Handling server responses}[rdoc-ref:Net::IMAP@Handling+server+responses]
+  # * {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands]
+  #   * {for any state}[rdoc-ref:Net::IMAP@Any+state]
+  #   * {for the "not authenticated" state}[rdoc-ref:Net::IMAP@Not+Authenticated+state]
+  #   * {for the "authenticated" state}[rdoc-ref:Net::IMAP@Authenticated+state]
+  #   * {for the "selected" state}[rdoc-ref:Net::IMAP@Selected+state]
+  #   * {for the "logout" state}[rdoc-ref:Net::IMAP@Logout+state]
+  # * {IMAP extension support}[rdoc-ref:Net::IMAP@IMAP+extension+support]
   #
   # === Connection control methods
   #
-  # - Net::IMAP.new: A new client connects immediately and waits for a
-  #   successful server greeting before returning the new client object.
+  # - Net::IMAP.new: Creates a new \IMAP client which connects immediately and
+  #   waits for a successful server greeting before the method returns.
   # - #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.
   # - #disconnect: Disconnects the connection (without sending #logout first).
   # - #disconnected?: True if the connection has been closed.
   #
+  # === Server capabilities
+  #
+  # - #capable?: Returns whether the server supports a given capability.
+  # - #capabilities: Returns the server's capabilities as an array of strings.
+  # - #auth_capable?: Returns whether the server advertises support for a given
+  #   SASL mechanism, for use with #authenticate.
+  # - #auth_mechanisms: Returns the #authenticate SASL mechanisms which
+  #   the server claims to support as an array of strings.
+  # - #clear_cached_capabilities: Clears cached capabilities.
+  #
+  #   <em>The capabilities cache is automatically cleared after completing
+  #   #starttls, #login, or #authenticate.</em>
+  # - #capability: Sends the +CAPABILITY+ command and returns the #capabilities.
+  #
+  #   <em>In general, #capable? should be used rather than explicitly sending a
+  #   +CAPABILITY+ command to the server.</em>
+  #
+  # === Handling server responses
+  #
+  # - #greeting: The server's initial untagged response, which can indicate a
+  #   pre-authenticated connection.
+  # - #responses: Yields unhandled UntaggedResponse#data and <em>non-+nil+</em>
+  #   ResponseCode#data.
+  # - #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.
+  # - #response_handlers: Returns the list of response handlers.
+  # - #remove_response_handler: Remove a previously added response handler.
+  #
   # === Core \IMAP commands
   #
   # The following commands are defined either by
@@ -199,69 +302,48 @@ module Net
   # [IDLE[https://tools.ietf.org/html/rfc2177]],
   # [NAMESPACE[https://tools.ietf.org/html/rfc2342]],
   # [UNSELECT[https://tools.ietf.org/html/rfc3691]],
-  #--
-  # TODO: [ENABLE[https://tools.ietf.org/html/rfc5161]],
-  # TODO: [LIST-EXTENDED[https://tools.ietf.org/html/rfc5258]],
-  # TODO: [LIST-STATUS[https://tools.ietf.org/html/rfc5819]],
-  #++
+  # [ENABLE[https://tools.ietf.org/html/rfc5161]],
   # [MOVE[https://tools.ietf.org/html/rfc6851]].
   # These extensions are widely supported by modern IMAP4rev1 servers and have
   # all been integrated into [IMAP4rev2[https://tools.ietf.org/html/rfc9051]].
-  # <em>Note: Net::IMAP doesn't fully support IMAP4rev2 yet.</em>
-  #
-  #--
-  # TODO: When IMAP4rev2 is supported, add the following to the each of the
-  # appropriate commands below.
-  #   Note:: CHECK has been removed from IMAP4rev2.
-  #   Note:: LSUB is obsoleted by +LIST-EXTENDED and has been removed from IMAP4rev2.
-  #   <em>Some arguments require the +LIST-EXTENDED+ or +IMAP4rev2+ capability.</em>
-  #   <em>Requires either the +ENABLE+    or +IMAP4rev2+ capability.</em>
-  #   <em>Requires either the +NAMESPACE+ or +IMAP4rev2+ capability.</em>
-  #   <em>Requires either the +IDLE+      or +IMAP4rev2+ capability.</em>
-  #   <em>Requires either the +UNSELECT+  or +IMAP4rev2+ capability.</em>
-  #   <em>Requires either the +UIDPLUS+   or +IMAP4rev2+ capability.</em>
-  #   <em>Requires either the +MOVE+      or +IMAP4rev2+ capability.</em>
-  #++
-  #
-  # ==== \IMAP commands for any state
+  # <em>*NOTE:* Net::IMAP doesn't support IMAP4rev2 yet.</em>
+  #
+  # ==== Any state
   #
   # - #capability: Returns the server's capabilities as an array of strings.
   #
-  #   <em>Capabilities may change after</em> #starttls, #authenticate, or #login
-  #   <em>and cached capabilities must be reloaded.</em>
+  #   <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.
   #
-  # ==== \IMAP commands for the "Not Authenticated" state
+  # ==== Not Authenticated state
   #
-  # In addition to the universal commands, the following commands are valid in
-  # the "<em>not authenticated</em>" state:
+  # In addition to the commands for any state, the following commands are valid
+  # in the "<em>not authenticated</em>" state:
   #
   # - #starttls: Upgrades a clear-text connection to use TLS.
   #
   #   <em>Requires the +STARTTLS+ capability.</em>
-  # - #authenticate: Identifies the client to the server using a {SASL
-  #   mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml].
-  #   Enters the "_authenticated_" state.
+  # - #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.
   #
-  #   <em>Requires the <tt>AUTH=#{mechanism}</tt> capability for the chosen
-  #   mechanism.</em>
+  #   <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.
   #
   #   <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
   #
-  # ==== \IMAP commands for the "Authenticated" state
-  #
-  # In addition to the universal commands, the following commands are valid in
-  # the "_authenticated_" state:
+  # ==== Authenticated state
   #
-  #--
-  # - #enable: <em>Not implemented by Net::IMAP, yet.</em>
+  # In addition to the commands for any state, the following commands are valid
+  # in the "_authenticated_" state:
   #
-  #   <em>Requires the +ENABLE+ capability.</em>
-  #++
+  # - #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.
   # - #create: Creates a new mailbox.
@@ -271,37 +353,31 @@ module Net
   # - #unsubscribe: Removes a mailbox from the "subscribed" set.
   # - #list: Returns names and attributes of mailboxes matching a given pattern.
   # - #namespace: Returns mailbox namespaces, with path prefixes and delimiters.
-  #
-  #   <em>Requires the +NAMESPACE+ capability.</em>
+  #   <em>Requires the +NAMESPACE+ or +IMAP4rev2+ capability.</em>
   # - #status: Returns mailbox information, e.g. message count, unseen message
   #   count, +UIDVALIDITY+ and +UIDNEXT+.
   # - #append: Appends a message to the end of a mailbox.
   # - #idle: Allows the server to send updates to the client, without the client
   #   needing to poll using #noop.
+  #   <em>Requires the +IDLE+ or +IMAP4rev2+ capability.</em>
+  # - *Obsolete* #lsub: <em>Replaced by <tt>LIST-EXTENDED</tt> and removed from
+  #   +IMAP4rev2+.</em>  Lists mailboxes in the "subscribed" set.
   #
-  #   <em>Requires the +IDLE+ capability.</em>
-  # - #lsub: Lists mailboxes the user has declared "active" or "subscribed".
-  #--
-  #   <em>Replaced by</em> <tt>LIST-EXTENDED</tt> <em>and removed from</em>
-  #   +IMAP4rev2+.  <em>However, Net::IMAP hasn't implemented</em>
-  #   <tt>LIST-EXTENDED</tt> _yet_.
-  #++
+  #   <em>*Note:* Net::IMAP hasn't implemented <tt>LIST-EXTENDED</tt> yet.</em>
   #
-  # ==== \IMAP commands for the "Selected" state
+  # ==== Selected state
   #
-  # In addition to the universal commands 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,
   #   expunging deleted messages, unless the mailbox was opened as read-only.
   # - #unselect: Closes the mailbox and returns to the "_authenticated_" state,
   #   without expunging any messages.
-  #
-  #   <em>Requires the +UNSELECT+ capability.</em>
+  #   <em>Requires the +UNSELECT+ or +IMAP4rev2+ capability.</em>
   # - #expunge: Permanently removes messages which have the Deleted flag set.
-  # - #uid_expunge: Restricts #expunge to only remove the specified UIDs.
-  #
-  #   <em>Requires the +UIDPLUS+ capability.</em>
+  # - #uid_expunge: Restricts expunge to only remove the specified UIDs.
+  #   <em>Requires the +UIDPLUS+ or +IMAP4rev2+ capability.</em>
   # - #search, #uid_search: Returns sequence numbers or UIDs of messages that
   #   match the given searching criteria.
   # - #fetch, #uid_fetch: Returns data associated with a set of messages,
@@ -311,45 +387,35 @@ module Net
   #   specified destination mailbox.
   # - #move, #uid_move: Moves the specified messages to the end of the
   #   specified destination mailbox, expunging them from the current mailbox.
+  #   <em>Requires the +MOVE+ or +IMAP4rev2+ capability.</em>
+  # - #check: <em>*Obsolete:* removed from +IMAP4rev2+.</em>
+  #   Can be replaced with #noop or #idle.
   #
-  #   <em>Requires the +MOVE+ capability.</em>
-  # - #check: Mostly obsolete.  Can be replaced with #noop or #idle.
-  #--
-  #   <em>Removed from IMAP4rev2.</em>
-  #++
-  #
-  # ==== \IMAP commands for the "Logout" state
+  # ==== 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.
   #
-  # === Supported \IMAP extensions
+  # === \IMAP extension support
   #
   # ==== RFC9051: +IMAP4rev2+
   #
-  # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is <em>not supported
-  # yet</em>, Net::IMAP supports several extensions that have been folded into
-  # it: +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+.
-  #--
-  # TODO: RFC4466, ABNF extensions (automatic support for other extensions)
-  # TODO: +ESEARCH+, ExtendedSearchData
-  # TODO: +SEARCHRES+,
-  # TODO: +ENABLE+,
-  # TODO: +SASL-IR+,
-  # TODO: +LIST-EXTENDED+,
-  # TODO: +LIST-STATUS+,
-  # TODO: +LITERAL-+,
-  # TODO: +BINARY+ (only the FETCH side)
-  # TODO: +SPECIAL-USE+
-  # implicitly supported, but we can do better: Response codes: RFC5530, etc
-  # implicitly supported, but we can do better: <tt>STATUS=SIZE</tt>
-  # implicitly supported, but we can do better: <tt>STATUS DELETED</tt>
-  #++
-  # Commands for these extensions are included with the {Core IMAP
-  # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.  Other supported
-  # extensons are listed below.
+  # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is not supported
+  # yet, Net::IMAP supports several extensions that have been folded into it:
+  # +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+, and +UNSELECT+.
+  # Commands for these extensions are listed with the {Core IMAP
+  # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.
+  #
+  # >>>
+  #   <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+, +LITERAL-+, +BINARY+ fetch, and +SPECIAL-USE+.  The
+  #   following extensions are implicitly supported, but will be updated with
+  #   more direct support: RFC5530 response codes, <tt>STATUS=SIZE</tt>, and
+  #   <tt>STATUS=DELETED</tt>.</em>
   #
   # ==== RFC2087: +QUOTA+
   # - #getquota: returns the resource usage and limits for a quota root
@@ -358,92 +424,47 @@ module Net
   # - #setquota: sets the resource limits for a given quota root.
   #
   # ==== RFC2177: +IDLE+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], so it is also
-  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/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], so it is also
-  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/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.
   #
   # ==== RFC2971: +ID+
   # - #id: exchanges client and server implementation information.
   #
-  #--
-  # ==== RFC3502: +MULTIAPPEND+
-  # TODO...
-  #++
-  #
-  #--
-  # ==== RFC3516: +BINARY+
-  # TODO...
-  #++
-  #
   # ==== RFC3691: +UNSELECT+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], so it is also
-  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/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.
   #
   # ==== RFC4314: +ACL+
   # - #getacl: lists the authenticated user's access rights to a mailbox.
   # - #setacl: sets the access rights for a user on a mailbox
-  #--
-  # TODO: #deleteacl, #listrights, #myrights
-  #++
-  # - *_Note:_* +DELETEACL+, +LISTRIGHTS+, and +MYRIGHTS+ are not supported yet.
+  # >>>
+  #   *NOTE:* +DELETEACL+, +LISTRIGHTS+, and +MYRIGHTS+ are not supported yet.
   #
   # ==== RFC4315: +UIDPLUS+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], so it is also
-  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/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
   #
-  #--
-  # ==== RFC4466: Collected Extensions to IMAP4 ABNF
-  # TODO...
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], this RFC updates
-  # the protocol to enable new optional parameters to many commands: #select,
-  # #examine, #create, #rename, #fetch, #uid_fetch, #store, #uid_store, #search,
-  # #uid_search, and #append.  However, specific parameters are not defined.
-  # Extensions to these commands use this syntax whenever possible.  Net::IMAP
-  # may be partially compatible with extensions to these commands, even without
-  # any explicit support.
-  #++
-  #
-  #--
-  # ==== RFC4731 +ESEARCH+
-  # TODO...
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
-  # - Updates #search, #uid_search to accept result options: +MIN+, +MAX+,
-  #   +ALL+, +COUNT+, and to return ExtendedSearchData.
-  #++
-  #
-  #--
   # ==== RFC4959: +SASL-IR+
-  # TODO...
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
-  # - Updates #authenticate to reduce round-trips for supporting mechanisms.
-  #++
-  #
-  #--
-  # ==== RFC4978: COMPRESS=DEFLATE
-  # TODO...
-  #++
+  # - Updates #authenticate with the option to send an initial response.
   #
-  #--
-  # ==== RFC5182 +SEARCHRES+
-  # TODO...
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
-  # - Updates #search, #uid_search with the +SAVE+ result option.
-  # - Updates #copy, #uid_copy, #fetch, #uid_fetch, #move, #uid_move, #search,
-  #   #uid_search, #store, #uid_store, and #uid_expunge with ability to
-  #   reference the saved result of a previous #search or #uid_search command.
-  #++
+  # ==== RFC5161: +ENABLE+
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
+  # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # - #enable: Enables backwards incompatible server extensions.
   #
   # ==== RFC5256: +SORT+
   # - #sort, #uid_sort: An alternate version of #search or #uid_search which
@@ -453,75 +474,20 @@ module Net
   #   which arranges the results into ordered groups or threads according to a
   #   chosen algorithm.
   #
-  #--
-  # ==== RFC5258 +LIST-EXTENDED+
-  # TODO...
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], this updates the
-  # protocol with new optional parameters to the #list command, adding a few of
-  # its own.  Net::IMAP may be forward-compatible with future #list extensions,
-  # even without any explicit support.
-  # - Updates #list to accept selection options: +SUBSCRIBED+, +REMOTE+, and
-  #   +RECURSIVEMATCH+, and return options: +SUBSCRIBED+ and +CHILDREN+.
-  #++
-  #
-  #--
-  # ==== RFC5819 +LIST-STATUS+
-  # TODO...
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
-  # - Updates #list with +STATUS+ return option.
-  #++
-  #
   # ==== +XLIST+ (non-standard, deprecated)
   # - #xlist: replaced by +SPECIAL-USE+ attributes in #list responses.
   #
-  #--
-  # ==== RFC6154 +SPECIAL-USE+
-  # TODO...
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051].
-  # - Updates #list with the +SPECIAL-USE+ selection and return options.
-  #++
-  #
   # ==== RFC6851: +MOVE+
-  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], so it is also
-  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/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.
   #
-  #--
-  # ==== RFC6855: UTF8=ACCEPT
-  # TODO...
-  # ==== RFC6855: UTF8=ONLY
-  # TODO...
-  #++
-  #
-  #--
-  # ==== RFC7888: <tt>LITERAL+</tt>, +LITERAL-+
-  # TODO...
-  # ==== RFC7162: +QRESYNC+
-  # TODO...
-  # ==== RFC7162: +CONDSTORE+
-  # TODO...
-  # ==== RFC8474: +OBJECTID+
-  # TODO...
-  # ==== RFC9208: +QUOTA+
-  # TODO...
-  #++
-  #
-  # === Handling server responses
-  #
-  # - #greeting: The server's initial untagged response, which can indicate a
-  #   pre-authenticated connection.
-  # - #responses: A hash with arrays of unhandled <em>non-+nil+</em>
-  #   UntaggedResponse and ResponseCode +#data+, keyed by +#name+.
-  # - #add_response_handler: Add a block to be called inside the receiver thread
-  #   with every server response.
-  # - #remove_response_handler: Remove a previously added response handler.
+  # ==== RFC6855: <tt>UTF8=ACCEPT</tt>, <tt>UTF8=ONLY</tt>
   #
+  # - See #enable for information about support for UTF-8 string encoding.
   #
   # == References
-  #--
-  # TODO: Consider moving references list to REFERENCES.md or REFERENCES.rdoc.
-  #++
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
   #   Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - \VERSION 4rev1",
@@ -622,27 +588,21 @@ module Net
   #    RFC 1864, DOI 10.17487/RFC1864, October 1995,
   #    <https://www.rfc-editor.org/info/rfc1864>.
   #
-  #--
-  # TODO: Document IMAP keywords.
-  #
-  # [RFC3503[https://tools.ietf.org/html/rfc3503]]
-  #   Melnikov, A., "Message Disposition Notification (MDN)
-  #   profile for Internet Message Access Protocol (IMAP)",
-  #   RFC 3503, DOI 10.17487/RFC3503, March 2003,
-  #   <https://www.rfc-editor.org/info/rfc3503>.
-  #++
+  # [RFC3503[https://tools.ietf.org/html/rfc3503]]::
+  #    Melnikov, A., "Message Disposition Notification (MDN)
+  #    profile for Internet Message Access Protocol (IMAP)",
+  #    RFC 3503, DOI 10.17487/RFC3503, March 2003,
+  #    <https://www.rfc-editor.org/info/rfc3503>.
   #
-  # === Supported \IMAP Extensions
+  # === \IMAP Extensions
   #
-  # [QUOTA[https://tools.ietf.org/html/rfc2087]]::
-  #   Myers, J., "IMAP4 QUOTA extension", RFC 2087, DOI 10.17487/RFC2087,
-  #   January 1997, <https://www.rfc-editor.org/info/rfc2087>.
-  #--
-  # TODO: test compatibility with updated QUOTA extension:
   # [QUOTA[https://tools.ietf.org/html/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>.
+  #   <em>Net::IMAP does not fully support the RFC9208 updates yet.</em>
   # [IDLE[https://tools.ietf.org/html/rfc2177]]::
   #   Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177,
   #   June 1997, <https://www.rfc-editor.org/info/rfc2177>.
@@ -675,31 +635,43 @@ 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://tools.ietf.org/html/rfc6855]]::
+  # [UTF8=ONLY[https://tools.ietf.org/html/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>.
   #
   # === IANA registries
-  #
   # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
   # * {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]
   # * {IMAP Threading Algorithms}[https://www.iana.org/assignments/imap-threading-algorithms/imap-threading-algorithms.xhtml]
-  #--
-  # * {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]
-  # * {IMAP URLAUTH Access Identifiers and Prefixes}[https://www.iana.org/assignments/urlauth-access-ids/urlauth-access-ids.xhtml]
-  # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
-  #++
   # * {SASL Mechanisms and SASL SCRAM Family Mechanisms}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
   # * {Service Name and Transport Protocol Port Number Registry}[https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml]:
   #   +imap+: tcp/143, +imaps+: tcp/993
   # * {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]
+  # * {IMAP URLAUTH Access Identifiers and Prefixes}[https://www.iana.org/assignments/urlauth-access-ids/urlauth-access-ids.xhtml]
+  # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.3.8"
+    VERSION = "0.4.0"
+
+    # Aliases for supported capabilities, to be used with the #enable command.
+    ENABLE_ALIASES = {
+      utf8:          "UTF8=ACCEPT",
+      "UTF8=ONLY" => "UTF8=ACCEPT",
+    }.freeze
+
+    autoload :SASL,       File.expand_path("imap/sasl",       __dir__)
+    autoload :StringPrep, File.expand_path("imap/stringprep", __dir__)
 
     include MonitorMixin
     if defined?(OpenSSL::SSL)
@@ -707,35 +679,6 @@ module Net
       include SSL
     end
 
-    # Returns the initial greeting the server, an UntaggedResponse.
-    attr_reader :greeting
-
-    # Returns a hash with arrays of unhandled <em>non-+nil+</em>
-    # UntaggedResponse#data keyed by UntaggedResponse#name, and
-    # ResponseCode#data keyed by ResponseCode#name.
-    #
-    # For example:
-    #
-    #   imap.select("inbox")
-    #   p imap.responses["EXISTS"][-1]
-    #   #=> 2
-    #   p imap.responses["UIDVALIDITY"][-1]
-    #   #=> 968263756
-    attr_reader :responses
-
-    # Returns all response handlers.
-    attr_reader :response_handlers
-
-    # 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
-
-    # Seconds to wait until an IDLE response is received.
-    attr_reader :idle_response_timeout
-
-    attr_accessor :client_thread # :nodoc:
-
     # Returns the debug mode.
     def self.debug
       return @@debug
@@ -762,9 +705,175 @@ module Net
       alias default_ssl_port default_tls_port
     end
 
+    # Returns the initial greeting 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
+
+    # Seconds to wait until an IDLE response is received.
+    attr_reader :idle_response_timeout
+
+    # The hostname this client connected to
+    attr_reader :host
+
+    # The port this client connected to
+    attr_reader :port
+
+    # Returns the
+    # {SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html]
+    # used by the SSLSocket when TLS is attempted, even when the TLS handshake
+    # is unsuccessful.  The context object will be frozen.
+    #
+    # Returns +nil+ for a plaintext connection.
+    attr_reader :ssl_ctx
+
+    # Returns the parameters that were sent to #ssl_ctx
+    # {set_params}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params]
+    # when the connection tries to use TLS (even when unsuccessful).
+    #
+    # Returns +false+ for a plaintext connection.
+    attr_reader :ssl_ctx_params
+
+    # Creates a new Net::IMAP object and connects it to the specified
+    # +host+.
+    #
+    # ==== Options
+    #
+    # Accepts the following options:
+    #
+    # [port]
+    #   Port number.  Defaults to 993 when +ssl+ is truthy, and 143 otherwise.
+    #
+    # [ssl]
+    #   If +true+, the connection will use TLS with the default params set by
+    #   {OpenSSL::SSL::SSLContext#set_params}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params].
+    #   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].
+    #
+    # [open_timeout]
+    #   Seconds to wait until a connection is opened
+    # [idle_response_timeout]
+    #   Seconds to wait until an IDLE response is received
+    #
+    # See DeprecatedClientOptions.new for deprecated arguments.
+    #
+    # ==== Examples
+    #
+    # Connect to cleartext port 143 at mail.example.com and recieve the server greeting:
+    #   imap = Net::IMAP.new('mail.example.com', ssl: false) # => #<Net::IMAP:0x00007f79b0872bd0>
+    #   imap.port          => 143
+    #   imap.tls_verified? => false
+    #   imap.greeting      => name: ("OK" | "PREAUTH") => status
+    #   status # => "OK"
+    #   # The client is connected in the "Not Authenticated" state.
+    #
+    # Connect with TLS to port 993
+    #   imap = Net::IMAP.new('mail.example.com', ssl: true) # => #<Net::IMAP:0x00007f79b0872bd0>
+    #   imap.port          => 993
+    #   imap.tls_verified? => true
+    #   imap.greeting      => name: (/OK/i | /PREAUTH/i) => status
+    #   case status
+    #   in /OK/i
+    #     # The client is connected in the "Not Authenticated" state.
+    #     imap.authenticate("PLAIN", "joe_user", "joes_password")
+    #   in /PREAUTH/i
+    #     # The client is connected in the "Authenticated" state.
+    #   end
+    #
+    # Connect with prior authentication, for example using an SSL certificate:
+    #   ssl_ctx_params = {
+    #     cert: OpenSSL::X509::Certificate.new(File.read("client.crt")),
+    #     key:  OpenSSL::PKey::EC.new(File.read('client.key')),
+    #     extra_chain_cert: [
+    #       OpenSSL::X509::Certificate.new(File.read("intermediate.crt")),
+    #     ],
+    #   }
+    #   imap = Net::IMAP.new('mail.example.com', ssl: ssl_ctx_params)
+    #   imap.port          => 993
+    #   imap.tls_verified? => true
+    #   imap.greeting      => name: "PREAUTH"
+    #   # The client is connected in the "Authenticated" state.
+    #
+    # ==== Exceptions
+    #
+    # The most common errors are:
+    #
+    # [Errno::ECONNREFUSED]
+    #   Connection refused by +host+ or an intervening firewall.
+    # [Errno::ETIMEDOUT]
+    #   Connection timed out (possibly due to packets being dropped by an
+    #   intervening firewall).
+    # [Errno::ENETUNREACH]
+    #   There is no route to that network.
+    # [SocketError]
+    #   Hostname not known or other socket error.
+    # [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)
+      super()
+      # Config options
+      @host = host
+      @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
+      @utf8_strings = false
+      @debug_output_bol = true
+      @exception = nil
+      @greeting = nil
+      @capabilities = nil
+
+      # Client Protocol Reciever
+      @parser = ResponseParser.new
+      @responses = Hash.new {|h, k| h[k] = [] }
+      @response_handlers = []
+      @receiver_thread = nil
+      @receiver_thread_exception = nil
+      @receiver_thread_terminating = false
+
+      # Client Protocol Sender (including state for currently running commands)
+      @tag_prefix = "RUBY"
+      @tagno = 0
+      @tagged_responses = {}
+      @tagged_response_arrival = new_cond
+      @continued_command_tag = nil
+      @continuation_request_arrival = new_cond
+      @continuation_request_exception = nil
+      @idle_done_cond = nil
+      @logout_command_tag = nil
+
+      # Connection
+      @tls_verified = false
+      @sock = tcp_socket(@host, @port)
+      start_tls_session if ssl_ctx
+      start_imap_connection
+
+      # DEPRECATED: to remove in next version
+      @client_thread = Thread.current
+    end
+
+    # Returns true after the TLS negotiation has completed and the remote
+    # hostname has been verified.  Returns false when TLS has been established
+    # 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
+    # Related: #logout, #logout!
     def disconnect
       return if disconnected?
       begin
@@ -794,62 +903,123 @@ module Net
       return @sock.closed?
     end
 
-    # Sends a {CAPABILITY command [IMAP4rev1 §6.1.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.1.1]
-    # and returns an array of capabilities that the server supports.  Each
-    # capability is a string.
+    # Returns whether the server supports a given +capability+.  When available,
+    # cached #capabilities are used without sending a new #capability command to
+    # the server.
     #
-    # See the {IANA IMAP4 capabilities
-    # registry}[http://www.iana.org/assignments/imap4-capabilities] for a list
-    # of all standard capabilities, and their reference RFCs.
+    # <em>*NOTE:* Most Net::IMAP methods do not _currently_ modify their
+    # behaviour according to the server's advertised #capabilities.</em>
     #
-    # >>>
-    #   <em>*Note* that Net::IMAP does not currently modify its
-    #   behaviour according to the capabilities of the server;
-    #   it is up to the user of the class to ensure that
-    #   a certain capability is supported by a server before
-    #   using it.</em>
+    # See Net::IMAP@Capabilities for more about \IMAP capabilities.
     #
-    # Capability requirements—other than +IMAP4rev1+—are listed in the
-    # documentation for each command method.
+    # Related: #auth_capable?, #capabilities, #capability, #enable
+    def capable?(capability) capabilities.include? capability.to_s.upcase end
+    alias capability? capable?
+
+    # Returns the server capabilities.  When available, cached capabilities are
+    # used without sending a new #capability command to the server.
+    #
+    # To ensure a case-insensitive comparison, #capable? can be used instead.
     #
-    # ===== Basic IMAP4rev1 capabilities
+    # <em>*NOTE:* Most Net::IMAP methods do not _currently_ modify their
+    # behaviour according to the server's advertised #capabilities.</em>
     #
-    # All IMAP4rev1 servers must include +IMAP4rev1+ in their capabilities list.
-    # All IMAP4rev1 servers must _implement_ the +STARTTLS+,
-    # <tt>AUTH=PLAIN</tt>, and +LOGINDISABLED+ capabilities, and clients must
-    # respect their presence or absence.  See the capabilites requirements on
-    # #starttls, #login, and #authenticate.
+    # See Net::IMAP@Capabilities for more about \IMAP capabilities.
     #
-    # ===== Using IMAP4rev1 extensions
+    # Related: #capable?, #auth_capable?, #auth_mechanisms, #capability, #enable
+    def capabilities
+      @capabilities || capability
+    end
+
+    # Returns the #authenticate mechanisms that the server claims to support.
+    # These are derived from the #capabilities with an <tt>AUTH=</tt> prefix.
     #
-    # IMAP4rev1 servers must not activate incompatible behavior until an
-    # explicit client action invokes a capability, e.g. sending a command or
-    # command argument specific to that capability.  Extensions with backward
-    # compatible behavior, such as response codes or mailbox attributes, may
-    # be sent at any time.
+    # This may be different when the connection is cleartext or using TLS.  Most
+    # servers will drop all <tt>AUTH=</tt> mechanisms from #capabilities after
+    # the connection has authenticated.
     #
-    # Invoking capabilities which are unknown to Net::IMAP may cause unexpected
-    # behavior and errors, for example ResponseParseError is raised when unknown
-    # response syntax is received.  Invoking commands or command parameters that
-    # are unsupported by the server may raise NoResponseError, BadResponseError,
-    # or cause other unexpected behavior.
+    #    imap = Net::IMAP.new(hostname, ssl: false)
+    #    imap.capabilities    # => ["IMAP4REV1", "LOGINDISABLED"]
+    #    imap.auth_mechanisms # => []
     #
-    # ===== Caching +CAPABILITY+ responses
+    #    imap.starttls
+    #    imap.capabilities    # => ["IMAP4REV1", "AUTH=PLAIN", "AUTH=XOAUTH2",
+    #                         #     "AUTH=OAUTHBEARER"]
+    #    imap.auth_mechanisms # => ["PLAIN", "XOAUTH2", "OAUTHBEARER"]
     #
-    # Servers may send their capability list, unsolicited, using the
-    # +CAPABILITY+ response code or an untagged +CAPABILITY+ response.  These
-    # responses can be retrieved and cached using #responses or
-    # #add_response_handler.
+    #    imap.authenticate("XOAUTH2", username, oauth2_access_token)
+    #    imap.auth_mechanisms # => []
+    #
+    # Related: #authenticate, #auth_capable?, #capabilities
+    def auth_mechanisms
+      capabilities
+        .grep(/\AAUTH=/i)
+        .map { _1.delete_prefix("AUTH=") }
+    end
+
+    # Returns whether the server supports a given SASL +mechanism+ for use with
+    # the #authenticate command.  The +mechanism+ is supported when
+    # #capabilities includes <tt>"AUTH=#{mechanism.to_s.upcase}"</tt>.  When
+    # available, cached capabilities are used without sending a new #capability
+    # command to the server.
+    #
+    #   imap.capable?      "AUTH=PLAIN"  # => true
+    #   imap.auth_capable? "PLAIN"       # => true
+    #   imap.auth_capable? "blurdybloop" # => false
+    #
+    # Related: #authenticate, #auth_mechanisms, #capable?, #capabilities
+    def auth_capable?(mechanism)
+      capable? "AUTH=#{mechanism}"
+    end
+
+    # Returns whether capabilities have been cached.  When true, #capable? and
+    # #capabilities don't require sending a #capability command to the server.
+    #
+    # See Net::IMAP@Capabilities for more about \IMAP capabilities.
+    #
+    # Related: #capable?, #capability, #clear_cached_capabilities
+    def capabilities_cached?
+      !!@capabilities
+    end
+
+    # Clears capabilities that have been remembered by the Net::IMAP client.
+    # This forces a #capability command to be sent the next time a #capabilities
+    # query method is called.
+    #
+    # Net::IMAP automatically discards its cached capabilities when they can
+    # change.  Explicitly calling this _should_ be unnecessary for well-behaved
+    # servers.
+    #
+    # Related: #capable?, #capability, #capabilities_cached?
+    def clear_cached_capabilities
+      synchronize do
+        clear_responses("CAPABILITY")
+        @capabilities = nil
+      end
+    end
+
+    # Sends a {CAPABILITY command [IMAP4rev1 §6.1.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.1.1]
+    # and returns an array of capabilities that are supported by the server.
+    # The result is stored for use by #capable? and #capabilities.
     #
-    # But cached capabilities _must_ be discarded after #starttls, #login, or
-    # #authenticate.  The OK TaggedResponse to #login and #authenticate may
-    # include +CAPABILITY+ response code data, but the TaggedResponse for
-    # #starttls is sent clear-text and cannot be trusted.
+    # <em>*NOTE:* Most Net::IMAP methods do not _currently_ modify their
+    # behaviour according to the server's advertised #capabilities.</em>
     #
+    # Net::IMAP automatically stores and discards capability data according to
+    # the requirements and recommendations in
+    # {IMAP4rev2 §6.1.1}[https://www.rfc-editor.org/rfc/rfc9051#section-6.1.1],
+    # {§6.2}[https://www.rfc-editor.org/rfc/rfc9051#section-6.2], and
+    # {§7.1}[https://www.rfc-editor.org/rfc/rfc9051#section-7.1].
+    # Use #capable?, #auth_capable?, or #capabilities to this cache and avoid
+    # sending the #capability command unnecessarily.
+    #
+    # See Net::IMAP@Capabilities for more about \IMAP capabilities.
+    #
+    # Related: #capable?, #auth_capable?, #capability, #enable
     def capability
       synchronize do
         send_command("CAPABILITY")
-        return @responses.delete("CAPABILITY")[-1]
+        @capabilities = clear_responses("CAPABILITY").last.freeze
       end
     end
 
@@ -860,8 +1030,7 @@ module Net
     # Note that the user should first check if the server supports the ID
     # capability. For example:
     #
-    #    capabilities = imap.capability
-    #    if capabilities.include?("ID")
+    #    if capable?(:ID)
     #      id = imap.id(
     #        name: "my IMAP client (ruby)",
     #        version: MyIMAP::VERSION,
@@ -879,7 +1048,7 @@ module Net
     def id(client_id=nil)
       synchronize do
         send_command("ID", ClientID.new(client_id))
-        @responses.delete("ID")&.last
+        clear_responses("ID").last
       end
     end
 
@@ -903,15 +1072,43 @@ module Net
     # to inform the command to inform the server that the client is done with
     # the connection.
     #
-    # Related: #disconnect
+    # Related: #disconnect, #logout!
     def logout
       send_command("LOGOUT")
     end
 
+    # Calls #logout then, after receiving the TaggedResponse for the +LOGOUT+,
+    # calls #disconnect.  Returns the TaggedResponse from +LOGOUT+.  Returns
+    # +nil+ when the client is already disconnected, in contrast to #logout
+    # which raises an exception.
+    #
+    # If #logout raises a StandardError, a warning will be printed but the
+    # exception will not be re-raised.
+    #
+    # This is useful in situations where the connection must be dropped, for
+    # example for security or after tests.  If logout errors need to be handled,
+    # use #logout and #disconnect instead.
+    #
+    # Related: #logout, #disconnect
+    def logout!
+      logout unless disconnected?
+    rescue => ex
+      warn "%s during <Net::IMAP %s:%s> logout!: %s" % [
+        ex.class, host, port, ex
+      ]
+    ensure
+      disconnect
+    end
+
     # Sends a {STARTTLS command [IMAP4rev1 §6.2.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.1]
     # to start a TLS session.
     #
-    # Any +options+ are forwarded to OpenSSL::SSL::SSLContext#set_params.
+    # Any +options+ are forwarded directly 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].
+    #
+    # See DeprecatedClientOptions#starttls for deprecated arguments.
     #
     # This method returns after TLS negotiation and hostname verification are
     # both successful.  Any error indicates that the connection has not been
@@ -921,132 +1118,156 @@ module Net
     # >>>
     #   Any #response_handlers added before STARTTLS should be aware that the
     #   TaggedResponse to STARTTLS is sent clear-text, _before_ TLS negotiation.
-    #   TLS negotiation starts immediately after that response.
+    #   TLS starts immediately _after_ that response.  Any response code sent
+    #   with the response (e.g. CAPABILITY) is insecure and cannot be trusted.
     #
     # Related: Net::IMAP.new, #login, #authenticate
     #
     # ===== Capability
-    #
-    # The server's capabilities must include +STARTTLS+.
+    # Clients should not call #starttls unless the server advertises the
+    # +STARTTLS+ capability.
     #
     # Server capabilities may change after #starttls, #login, and #authenticate.
-    # Cached capabilities _must_ be invalidated after this method completes.
-    #
-    # The TaggedResponse to #starttls is sent clear-text, so the server <em>must
-    # *not*</em> send capabilities in the #starttls response and clients <em>must
-    # not</em> use them if they are sent.  Servers will generally send an
-    # unsolicited untagged response immeditely _after_ #starttls completes.
+    # Cached #capabilities will be cleared when this method completes.
     #
-    def starttls(options = {}, verify = true)
+    def starttls(**options)
+      @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options)
       send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
-          begin
-            # for backward compatibility
-            certs = options.to_str
-            options = create_ssl_params(certs, verify)
-          rescue NoMethodError
-          end
-          start_tls_session(options)
+          clear_cached_capabilities
+          clear_responses
+          start_tls_session
         end
       end
     end
 
     # :call-seq:
-    #   authenticate(mechanism, ...)                               -> ok_resp
-    #   authenticate(mech, *creds, **props) {|prop, auth| val }    -> ok_resp
-    #   authenticate(mechanism, authnid, credentials, authzid=nil) -> ok_resp
-    #   authenticate(mechanism, **properties)                      -> ok_resp
-    #   authenticate(mechanism) {|propname, authctx| prop_value }  -> ok_resp
+    #   authenticate(mechanism, *, sasl_ir: true, **, &) -> 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
     # "_authenticated_" state.
     #
     # +mechanism+ is the name of the \SASL authentication mechanism to be used.
-    # All other arguments are forwarded to the authenticator for the requested
-    # mechanism.  The listed call signatures are suggestions.  <em>The
-    # documentation for each individual mechanism must be consulted for its
-    # specific parameters.</em>
     #
-    # An exception Net::IMAP::NoResponseError is raised if authentication fails.
+    # +sasl_ir+ allows or disallows sending an "initial response" (see the
+    # +SASL-IR+ capability, below).
     #
-    # Related: #login, #starttls
+    # All other arguments are forwarded to the registered SASL authenticator for
+    # the requested mechanism.  <em>The documentation for each individual
+    # mechanism must be consulted for its specific parameters.</em>
     #
-    # ==== Supported SASL Mechanisms
+    # Related: #login, #starttls, #auth_capable?, #auth_mechanisms
     #
-    # +PLAIN+::     See PlainAuthenticator.
-    #               Login using clear-text username and password.
+    # ==== Mechanisms
     #
-    # +XOAUTH2+::   See XOauth2Authenticator.
-    #               Login using a username and OAuth2 access token.
-    #               Non-standard and obsoleted by +OAUTHBEARER+, but widely
-    #               supported.
+    # Each mechanism has different properties and requirements.  Please consult
+    # the documentation for the specific mechanisms you are using:
     #
-    # >>>
-    #   *Deprecated:*  <em>Obsolete mechanisms are available for backwards
-    #   compatibility.</em>
+    # +ANONYMOUS+::
+    #     See AnonymousAuthenticator[rdoc-ref:Net::IMAP::SASL::AnonymousAuthenticator].
+    #
+    #     Allows the user to gain access to public services or resources without
+    #     authenticating or disclosing an identity.
+    #
+    # +EXTERNAL+::
+    #     See ExternalAuthenticator[rdoc-ref:Net::IMAP::SASL::ExternalAuthenticator].
+    #
+    #     Authenticates using already established credentials, such as a TLS
+    #     certificate or IPsec.
+    #
+    # +OAUTHBEARER+::
+    #     See OAuthBearerAuthenticator[rdoc-ref:Net::IMAP::SASL::OAuthBearerAuthenticator].
+    #
+    #     Login using an OAuth2 Bearer token.  This is the standard mechanism
+    #     for using OAuth2 with \SASL, but it is not yet deployed as widely as
+    #     +XOAUTH2+.
     #
-    #   For +DIGEST-MD5+ see DigestMD5Authenticator.
+    # +PLAIN+::
+    #     See PlainAuthenticator[rdoc-ref:Net::IMAP::SASL::PlainAuthenticator].
     #
-    #   For +LOGIN+, see LoginAuthenticator.
+    #     Login using clear-text username and password.
     #
-    #   For +CRAM-MD5+, see CramMD5Authenticator.
+    # +SCRAM-SHA-1+::
+    # +SCRAM-SHA-256+::
+    #     See ScramAuthenticator[rdoc-ref:Net::IMAP::SASL::ScramAuthenticator].
     #
-    #   <em>Using a deprecated mechanism will print a warning.</em>
+    #     Login by username and password.  The password is not sent to the
+    #     server but is used in a salted challenge/response exchange.
+    #     +SCRAM-SHA-1+ and +SCRAM-SHA-256+ are directly supported by
+    #     Net::IMAP::SASL.  New authenticators can easily be added for any other
+    #     <tt>SCRAM-*</tt> mechanism if the digest algorithm is supported by
+    #     OpenSSL::Digest.
     #
-    # See Net::IMAP::Authenticators for information on plugging in
-    # authenticators for other mechanisms.  See the {SASL mechanism
+    # +XOAUTH2+::
+    #     See XOAuth2Authenticator[rdoc-ref:Net::IMAP::SASL::XOAuth2Authenticator].
+    #
+    #     Login using a username and an OAuth2 access token.  Non-standard and
+    #     obsoleted by +OAUTHBEARER+, but widely supported.
+    #
+    # See the {SASL mechanism
     # registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-    # for information on these and other SASL mechanisms.
+    # for a list of all SASL mechanisms and their specifications.  To register
+    # new authenticators, see Authenticators.
     #
-    # ===== Capabilities
+    # ===== Deprecated mechanisms
     #
-    # Clients MUST NOT attempt to authenticate with a mechanism unless
-    # <tt>"AUTH=#{mechanism}"</tt> for that mechanism is a server capability.
+    # <em>Obsolete mechanisms should be avoided, but are still available for
+    # backwards compatibility.  See</em> Net::IMAP::SASL@Deprecated+mechanisms.
+    # <em>Using a deprecated mechanism will print a warning.</em>
     #
-    # Server capabilities may change after #starttls, #login, and #authenticate.
-    # Cached capabilities _must_ be invalidated after this method completes.
-    # The TaggedResponse to #authenticate may include updated capabilities in
-    # its ResponseCode.
-    #
-    # ===== Example
-    # If the authenticators ignore unhandled keyword arguments, the same config
-    # can be used for multiple mechanisms:
-    #
-    #    password  = nil # saved locally, so we don't ask more than once
-    #    accesstok = nil # saved locally...
-    #    creds = {
-    #      authcid:      username,
-    #      password:     proc { password  ||= ui.prompt_for_password },
-    #      oauth2_token: proc { accesstok ||= kms.fresh_access_token },
-    #    }
-    #    capa = imap.capability
-    #    if    capa.include? "AUTH=OAUTHBEARER"
-    #      imap.authenticate "OAUTHBEARER",   **creds # authcid, oauth2_token
-    #    elsif capa.include? "AUTH=XOAUTH2"
-    #      imap.authenticate "XOAUTH2",       **creds # authcid, oauth2_token
-    #    elsif capa.include? "AUTH=SCRAM-SHA-256"
-    #      imap.authenticate "SCRAM-SHA-256", **creds # authcid, password
-    #    elsif capa.include? "AUTH=PLAIN"
-    #      imap.authenticate "PLAIN",         **creds # authcid, password
-    #    elsif capa.include? "AUTH=DIGEST-MD5"
-    #      imap.authenticate "DIGEST-MD5",    **creds # authcid, password
-    #    elsif capa.include? "LOGINDISABLED"
-    #      raise "the server has disabled login"
-    #    else
+    # ==== Capabilities
+    #
+    # <tt>"AUTH=#{mechanism}"</tt> capabilities indicate server support for
+    # mechanisms.  Use #auth_capable? or #auth_mechanisms to check for support
+    # before using a particular mechanism.
+    #
+    #    if imap.auth_capable? "XOAUTH2"
+    #      imap.authenticate "XOAUTH2", username, oauth2_access_token
+    #    elsif imap.auth_capable? "PLAIN"
+    #      imap.authenticate "PLAIN", username, password
+    #    elsif !imap.capability? "LOGINDISABLED"
     #      imap.login username, password
+    #    else
+    #      raise "No acceptable authentication mechanism is available"
     #    end
     #
-    def authenticate(mechanism, *args, **props, &cb)
-      authenticator = self.class.authenticator(mechanism, *args, **props, &cb)
-      send_command("AUTHENTICATE", mechanism) do |resp|
-        if resp.instance_of?(ContinuationRequest)
-          data = authenticator.process(resp.data.text.unpack("m")[0])
-          s = [data].pack("m0")
-          send_string_data(s)
-          put_string(CRLF)
-        end
+    # Although servers should list all supported \SASL mechanisms, they may
+    # allow authentication with an unlisted +mechanism+.
+    #
+    # If [SASL-IR[https://www.rfc-editor.org/rfc/rfc4959.html]] is supported
+    # and the appropriate <tt>"AUTH=#{mechanism}"</tt> capability is present,
+    # an "initial response" may be sent as an argument to the +AUTHENTICATE+
+    # command, saving a round-trip.  The SASL exchange allows for server
+    # challenges and client responses, but many mechanisms expect the client to
+    # "respond" first.  The initial response will only be sent for
+    # "client-first" mechanisms.
+    #
+    # Server capabilities may change after #starttls, #login, and #authenticate.
+    # 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
     end
 
     # Sends a {LOGIN command [IMAP4rev1 §6.2.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.3]
@@ -1054,16 +1275,25 @@ module Net
     # this +user+.  If successful, the connection enters the "_authenticated_"
     # state.
     #
-    # Using #authenticate is generally preferred over #login.  The LOGIN command
-    # is not the same as #authenticate with the "LOGIN" +mechanism+.
+    # Using #authenticate {should be
+    # preferred}[https://www.rfc-editor.org/rfc/rfc9051.html#name-login-command]
+    # over #login.  The LOGIN command is not the same as #authenticate with the
+    # "LOGIN" +mechanism+.
     #
     # A Net::IMAP::NoResponseError is raised if authentication fails.
     #
     # Related: #authenticate, #starttls
     #
-    # ==== Capabilities
-    # Clients MUST NOT call #login if +LOGINDISABLED+ is listed with the
-    # 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
     #
     # Server capabilities may change after #starttls, #login, and #authenticate.
     # Cached capabilities _must_ be invalidated after this method completes.
@@ -1072,17 +1302,18 @@ module Net
     #
     def login(user, password)
       send_command("LOGIN", user, password)
+        .tap { @capabilities = capabilities_from_resp_code _1 }
     end
 
     # Sends a {SELECT command [IMAP4rev1 §6.3.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.1]
     # to select a +mailbox+ so that messages in the +mailbox+ can be accessed.
     #
     # After you have selected a mailbox, you may retrieve the number of items in
-    # that mailbox from <tt>imap.responses["EXISTS"][-1]</tt>, and the number of
-    # recent messages from <tt>imap.responses["RECENT"][-1]</tt>.  Note that
-    # these values can change if new messages arrive during a session or when
-    # existing messages are expunged; see #add_response_handler for a way to
-    # detect these events.
+    # that mailbox from <tt>imap.responses("EXISTS", &:last)</tt>, and the
+    # number of recent messages from <tt>imap.responses("RECENT", &:last)</tt>.
+    # Note that these values can change if new messages arrive during a session
+    # or when existing messages are expunged; see #add_response_handler for a
+    # way to detect these events.
     #
     # A Net::IMAP::NoResponseError is raised if the mailbox does not
     # exist or is for some reason non-selectable.
@@ -1213,7 +1444,7 @@ module Net
     def list(refname, mailbox)
       synchronize do
         send_command("LIST", refname, mailbox)
-        return @responses.delete("LIST")
+        clear_responses("LIST")
       end
     end
 
@@ -1251,8 +1482,7 @@ module Net
     #
     # ===== For example:
     #
-    #    capabilities = imap.capability
-    #    if capabilities.include?("NAMESPACE")
+    #    if capable?("NAMESPACE")
     #      namespaces = imap.namespace
     #      if namespace = namespaces.personal.first
     #        prefix = namespace.prefix  # e.g. "" or "INBOX."
@@ -1271,7 +1501,7 @@ module Net
     def namespace
       synchronize do
         send_command("NAMESPACE")
-        return @responses.delete("NAMESPACE")[-1]
+        clear_responses("NAMESPACE").last
       end
     end
 
@@ -1315,7 +1545,7 @@ module Net
     def xlist(refname, mailbox)
       synchronize do
         send_command("XLIST", refname, mailbox)
-        return @responses.delete("XLIST")
+        clear_responses("XLIST")
       end
     end
 
@@ -1334,8 +1564,8 @@ module Net
       synchronize do
         send_command("GETQUOTAROOT", mailbox)
         result = []
-        result.concat(@responses.delete("QUOTAROOT"))
-        result.concat(@responses.delete("QUOTA"))
+        result.concat(clear_responses("QUOTAROOT"))
+        result.concat(clear_responses("QUOTA"))
         return result
       end
     end
@@ -1354,7 +1584,7 @@ module Net
     def getquota(mailbox)
       synchronize do
         send_command("GETQUOTA", mailbox)
-        return @responses.delete("QUOTA")
+        clear_responses("QUOTA")
       end
     end
 
@@ -1410,7 +1640,7 @@ module Net
     def getacl(mailbox)
       synchronize do
         send_command("GETACL", mailbox)
-        return @responses.delete("ACL")[-1]
+        clear_responses("ACL").last
       end
     end
 
@@ -1425,7 +1655,7 @@ module Net
     def lsub(refname, mailbox)
       synchronize do
         send_command("LSUB", refname, mailbox)
-        return @responses.delete("LSUB")
+        clear_responses("LSUB")
       end
     end
 
@@ -1449,7 +1679,7 @@ module Net
     def status(mailbox, attr)
       synchronize do
         send_command("STATUS", mailbox, attr)
-        return @responses.delete("STATUS")[-1].attr
+        clear_responses("STATUS").last&.attr
       end
     end
 
@@ -1538,7 +1768,7 @@ module Net
     def expunge
       synchronize do
         send_command("EXPUNGE")
-        return @responses.delete("EXPUNGE")
+        clear_responses("EXPUNGE")
       end
     end
 
@@ -1570,7 +1800,7 @@ module Net
     def uid_expunge(uid_set)
       synchronize do
         send_command("UID EXPUNGE", MessageSet.new(uid_set))
-        return @responses.delete("EXPUNGE")
+        clear_responses("EXPUNGE")
       end
     end
 
@@ -1589,7 +1819,7 @@ module Net
     # 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 #capability which may define additional search filters, e.g:
+    # reported by #capabilities which may define additional search filters, e.g:
     # +CONDSTORE+, +WITHIN+, +FILTERS+, <tt>SEARCH=FUZZY</tt>, +OBJECTID+, or
     # +SAVEDATE+.  The following are some common search criteria:
     #
@@ -1884,6 +2114,87 @@ module Net
       return thread_internal("UID THREAD", algorithm, search_keys, charset)
     end
 
+    # Sends an {ENABLE command [RFC5161 §3.2]}[https://www.rfc-editor.org/rfc/rfc5161#section-3.1]
+    # {[IMAP4rev2 §6.3.1]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.1]
+    # to enable the specified server +capabilities+.  Each capability may be an
+    # array, string, or symbol.  Returns a list of the capabilities that were
+    # enabled.
+    #
+    # The +ENABLE+ command is only valid in the _authenticated_ state, before
+    # any mailbox is selected.
+    #
+    # Related: #capable?, #capabilities, #capability
+    #
+    # ===== Capabilities
+    #
+    # The server's capabilities must include
+    # +ENABLE+ [RFC5161[https://tools.ietf.org/html/rfc5161]]
+    # or +IMAP4REV2+ [RFC9051[https://tools.ietf.org/html/rfc9051]].
+    #
+    # Additionally, the server capabilities must include a capability matching
+    # each enabled extension (usually the same name as the enabled extension).
+    # The following capabilities may be enabled:
+    #
+    # [+:utf8+ --- an alias for <tt>"UTF8=ACCEPT"</tt>]
+    #
+    #   In a future release, <tt>enable(:utf8)</tt> will enable either
+    #   <tt>"UTF8=ACCEPT"</tt> or <tt>"IMAP4rev2"</tt>, depending on server
+    #   capabilities.
+    #
+    # [<tt>"UTF8=ACCEPT"</tt> [RFC6855[https://tools.ietf.org/html/rfc6855]]]
+    #
+    #   The server's capabilities must include <tt>UTF8=ACCEPT</tt> _or_
+    #   <tt>UTF8=ONLY</tt>.
+    #
+    #   This allows the server to send strings encoded as UTF-8 which might
+    #   otherwise need to use a 7-bit encoding, such as {modified
+    #   UTF-7}[::decode_utf7] for mailbox names, or RFC2047 encoded-words for
+    #   message headers.
+    #
+    #   *Note:* <em>A future update may set string encodings slightly
+    #   differently</em>, e.g: "US-ASCII" when UTF-8 is not enabled, and "UTF-8"
+    #   when it is.  Currently, the encoding of strings sent as "quoted" or
+    #   "text" will _always_ be "UTF-8", even when only ASCII characters are
+    #   used (e.g. "Subject: Agenda") And currently, string "literals" sent
+    #   by the server will always have an "ASCII-8BIT" (binary)
+    #   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]]]
+    #
+    #   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>.
+    #
+    # ===== Unsupported capabilities
+    #
+    # *Note:* Some extensions that use ENABLE permit the server to send syntax
+    # that Net::IMAP cannot parse, which may raise an exception and disconnect.
+    # Some extensions may work, but the support may be incomplete, untested, or
+    # experimental.
+    #
+    # Until a capability is documented here as supported, enabling it may result
+    # in undocumented behavior and a future release may update with incompatible
+    # behavior <em>without warning or deprecation</em>.
+    #
+    # <em>Caution is advised.</em>
+    #
+    def enable(*capabilities)
+      capabilities = capabilities
+        .flatten
+        .map {|e| ENABLE_ALIASES[e] || e }
+        .uniq
+        .join(' ')
+      synchronize do
+        send_command("ENABLE #{capabilities}")
+        result = clear_responses("ENABLED").last
+        @utf8_strings ||= result.include? "UTF8=ACCEPT"
+        @utf8_strings ||= result.include? "IMAP4REV2"
+        result
+      end
+    end
+
     # Sends an {IDLE command [RFC2177 §3]}[https://www.rfc-editor.org/rfc/rfc6851#section-3]
     # {[IMAP4rev2 §6.3.13]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.13]
     # that waits for notifications of new or expunged messages.  Yields
@@ -1948,6 +2259,104 @@ module Net
       end
     end
 
+    # :call-seq:
+    #   responses       {|hash|  ...} -> block result
+    #   responses(type) {|array| ...} -> block result
+    #
+    # Yields unhandled responses and returns the result of the block.
+    #
+    # 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.
+    #
+    # For example:
+    #
+    #   imap.select("inbox")
+    #   p imap.responses("EXISTS", &:last)
+    #   #=> 2
+    #   p imap.responses("UIDVALIDITY", &:last)
+    #   #=> 968263756
+    #
+    # >>>
+    #   *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.
+    #
+    #   Calling without a block is unsafe and deprecated.  Future releases will
+    #   raise ArgumentError unless a block is given.
+    #
+    # 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.
+    #
+    # 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
+    # attached to.  ResponseText will be accessible by its response types:
+    # "+OK+", "+NO+", "+BAD+", "+BYE+", or "+PREAUTH+".
+    #
+    # TaggedResponse#data is not saved to #responses, nor is any
+    # 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"
+      else
+        # warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+        @responses
+      end
+    end
+
+    # :call-seq:
+    #   clear_responses       -> hash
+    #   clear_responses(type) -> array
+    #
+    # Clears and returns the unhandled #responses hash or the unhandled
+    # responses array for a single response +type+.
+    #
+    # Clearing responses is synchronized with other threads.  The lock is
+    # released before returning.
+    #
+    # Related: #responses, #response_handlers
+    def clear_responses(type = nil)
+      synchronize {
+        if type
+          @responses.delete(type) || []
+        else
+          @responses.dup.transform_values(&:freeze)
+            .tap { _1.default = [].freeze }
+            .tap { @responses.clear }
+        end
+      }
+        .freeze
+    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.
+    #
+    # Response handlers are called with a mutex inside the receiver thread.  New
+    # responses cannot be processed and commands from other threads must wait
+    # until all response_handlers return.  An exception will shut-down the
+    # receiver thread and close the connection.
+    #
+    # For thread-safety, the returned array is a frozen copy of the internal
+    # array.
+    #
+    # Related: #add_response_handler, #remove_response_handler
+    def response_handlers
+      synchronize { @response_handlers.clone.freeze }
+    end
+
     # Adds a response handler. For example, to detect when
     # the server sends a new EXISTS response (which normally
     # indicates new messages being added to the mailbox),
@@ -1960,14 +2369,21 @@ module Net
     #     end
     #   }
     #
+    # Related: #remove_response_handler, #response_handlers
     def add_response_handler(handler = nil, &block)
       raise ArgumentError, "two Procs are passed" if handler && block
-      @response_handlers.push(block || handler)
+      synchronize do
+        @response_handlers.push(block || handler)
+      end
     end
 
     # Removes the response handler.
+    #
+    # Related: #add_response_handler, #response_handlers
     def remove_response_handler(handler)
-      @response_handlers.delete(handler)
+      synchronize do
+        @response_handlers.delete(handler)
+      end
     end
 
     private
@@ -1978,93 +2394,29 @@ module Net
 
     @@debug = false
 
-    # :call-seq:
-    #    Net::IMAP.new(host, options = {})
-    #
-    # Creates a new Net::IMAP object and connects it to the specified
-    # +host+.
-    #
-    # +options+ is an option hash, each key of which is a symbol.
-    #
-    # The available options are:
-    #
-    # port::  Port number (default value is 143 for imap, or 993 for imaps)
-    # ssl::   If +options[:ssl]+ is true, then an attempt will be made
-    #         to use SSL (now TLS) to connect to the server.
-    #         If +options[:ssl]+ is a hash, it's passed to
-    #         OpenSSL::SSL::SSLContext#set_params as parameters.
-    # open_timeout:: Seconds to wait until a connection is opened
-    # idle_response_timeout:: Seconds to wait until an IDLE response is received
-    #
-    # The most common errors are:
-    #
-    # Errno::ECONNREFUSED:: Connection refused by +host+ or an intervening
-    #                       firewall.
-    # Errno::ETIMEDOUT:: Connection timed out (possibly due to packets
-    #                    being dropped by an intervening firewall).
-    # Errno::ENETUNREACH:: There is no route to that network.
-    # SocketError:: Hostname not known or other socket error.
-    # Net::IMAP::ByeResponseError:: The connected to the host was successful, but
-    #                               it immediately said goodbye.
-    def initialize(host, port_or_options = {},
-                   usessl = false, certs = nil, verify = true)
-      super()
-      @host = host
-      begin
-        options = port_or_options.to_hash
-      rescue NoMethodError
-        # for backward compatibility
-        options = {}
-        options[:port] = port_or_options
-        if usessl
-          options[:ssl] = create_ssl_params(certs, verify)
-        end
-      end
-      @port = options[:port] || (options[:ssl] ? SSL_PORT : PORT)
-      @tag_prefix = "RUBY"
-      @tagno = 0
-      @open_timeout = options[:open_timeout] || 30
-      @idle_response_timeout = options[:idle_response_timeout] || 5
-      @parser = ResponseParser.new
-      @sock = tcp_socket(@host, @port)
-      begin
-        if options[:ssl]
-          start_tls_session(options[:ssl])
-          @usessl = true
-        else
-          @usessl = false
-        end
-        @responses = Hash.new([].freeze)
-        @tagged_responses = {}
-        @response_handlers = []
-        @tagged_response_arrival = new_cond
-        @continued_command_tag = nil
-        @continuation_request_arrival = new_cond
-        @continuation_request_exception = nil
-        @idle_done_cond = nil
-        @logout_command_tag = nil
-        @debug_output_bol = true
-        @exception = nil
-
-        @greeting = get_response
-        if @greeting.nil?
-          raise Error, "connection closed"
-        end
-        if @greeting.name == "BYE"
-          raise ByeResponseError, @greeting
-        end
-
-        @client_thread = Thread.current
-        @receiver_thread = Thread.start {
-          begin
-            receive_responses
-          rescue Exception
-          end
-        }
-        @receiver_thread_terminating = false
-      rescue Exception
-        @sock.close
-        raise
+    def start_imap_connection
+      @greeting        = get_server_greeting
+      @capabilities    = capabilities_from_resp_code @greeting
+      @receiver_thread = start_receiver_thread
+    rescue Exception
+      @sock.close
+      raise
+    end
+
+    def get_server_greeting
+      greeting = get_response
+      raise Error, "No server greeting - connection closed" unless greeting
+      record_untagged_response_code greeting
+      raise ByeResponseError, greeting if greeting.name == "BYE"
+      greeting
+    end
+
+    def start_receiver_thread
+      Thread.start do
+        receive_responses
+      rescue Exception => ex
+        @receiver_thread_exception = ex
+        # don't exit the thread with an exception
       end
     end
 
@@ -2113,11 +2465,7 @@ module Net
                 @continuation_request_arrival.signal
               end
             when UntaggedResponse
-              record_response(resp.name, resp.data)
-              if resp.data.instance_of?(ResponseText) &&
-                  (code = resp.data.code)
-                record_response(code.name, code.data)
-              end
+              record_untagged_response(resp)
               if resp.name == "BYE" && @logout_command_tag.nil?
                 @sock.close
                 @exception = ByeResponseError.new(resp)
@@ -2195,11 +2543,42 @@ module Net
       return @parser.parse(buff)
     end
 
-    def record_response(name, data)
-      unless @responses.has_key?(name)
-        @responses[name] = []
+    #############################
+    # built-in response handlers
+
+    # store name => [..., data]
+    def record_untagged_response(resp)
+      @responses[resp.name] << resp.data
+      record_untagged_response_code resp
+    end
+
+    # store code.name => [..., code.data]
+    def record_untagged_response_code(resp)
+      return unless resp.data.is_a?(ResponseText)
+      return unless (code = resp.data.code)
+      @responses[code.name] << code.data
+    end
+
+    # NOTE: only call this for greeting, login, and authenticate
+    def capabilities_from_resp_code(resp)
+      return unless %w[PREAUTH OK].any? { _1.casecmp? resp.name }
+      return unless (code = resp.data.code)
+      return unless code.name.casecmp?("CAPABILITY")
+      code.data.freeze
+    end
+
+    #############################
+
+    # Calls send_command, yielding the text of each ContinuationRequest and
+    # responding with each block result.  Returns TaggedResponse.  Raises
+    # NoResponseError or BadResponseError.
+    def send_command_with_continuations(cmd, *args)
+      send_command(cmd, *args) do |server_response|
+        if server_response.instance_of?(ContinuationRequest)
+          client_response = yield server_response.data.text
+          put_string(client_response + CRLF)
+        end
       end
-      @responses[name].push(data)
     end
 
     def send_command(cmd, *args, &block)
@@ -2241,8 +2620,8 @@ module Net
         if @debug_output_bol
           $stderr.print("C: ")
         end
-        $stderr.print(str.gsub(/\n(?!\z)/n, "\nC: "))
-        if /\r\n\z/n.match(str)
+        $stderr.print(str.gsub(/\n/n) { $'.empty? ? $& : "\nC: " })
+        if /\n\z/n.match(str)
           @debug_output_bol = true
         else
           @debug_output_bol = false
@@ -2262,7 +2641,7 @@ module Net
         else
           send_command(cmd, *keys)
         end
-        return @responses.delete("SEARCH")[-1]
+        clear_responses("SEARCH").last
       end
     end
 
@@ -2277,13 +2656,13 @@ module Net
       end
 
       synchronize do
-        @responses.delete("FETCH")
+        clear_responses("FETCH")
         if mod
           send_command(cmd, MessageSet.new(set), attr, mod)
         else
           send_command(cmd, MessageSet.new(set), attr)
         end
-        return @responses.delete("FETCH")
+        clear_responses("FETCH")
       end
     end
 
@@ -2292,9 +2671,9 @@ module Net
         attr = RawData.new(attr)
       end
       synchronize do
-        @responses.delete("FETCH")
+        clear_responses("FETCH")
         send_command(cmd, MessageSet.new(set), attr, flags)
-        return @responses.delete("FETCH")
+        clear_responses("FETCH")
       end
     end
 
@@ -2311,7 +2690,7 @@ module Net
       normalize_searching_criteria(search_keys)
       synchronize do
         send_command(cmd, sort_keys, charset, *search_keys)
-        return @responses.delete("SORT")[-1]
+        clear_responses("SORT").last
       end
     end
 
@@ -2322,8 +2701,10 @@ module Net
         normalize_searching_criteria(search_keys)
       end
       normalize_searching_criteria(search_keys)
-      send_command(cmd, algorithm, charset, *search_keys)
-      return @responses.delete("THREAD")[-1]
+      synchronize do
+        send_command(cmd, algorithm, charset, *search_keys)
+        clear_responses("THREAD").last
+      end
     end
 
     def normalize_searching_criteria(keys)
@@ -2337,49 +2718,45 @@ module Net
       end
     end
 
-    def create_ssl_params(certs = nil, verify = true)
-      params = {}
-      if certs
-        if File.file?(certs)
-          params[:ca_file] = certs
-        elsif File.directory?(certs)
-          params[:ca_path] = certs
+    def build_ssl_ctx(ssl)
+      if ssl
+        params = (Hash.try_convert(ssl) || {}).freeze
+        context = SSLContext.new
+        context.set_params(params)
+        if defined?(VerifyCallbackProc)
+          context.verify_callback = VerifyCallbackProc
         end
-      end
-      if verify
-        params[:verify_mode] = VERIFY_PEER
+        context.freeze
+        [params, context]
       else
-        params[:verify_mode] = VERIFY_NONE
+        false
       end
-      return params
     end
 
-    def start_tls_session(params = {})
-      unless defined?(OpenSSL::SSL)
-        raise "SSL extension not installed"
-      end
-      if @sock.kind_of?(OpenSSL::SSL::SSLSocket)
-        raise RuntimeError, "already using SSL"
-      end
-      begin
-        params = params.to_hash
-      rescue NoMethodError
-        params = {}
-      end
-      context = SSLContext.new
-      context.set_params(params)
-      if defined?(VerifyCallbackProc)
-        context.verify_callback = VerifyCallbackProc
-      end
-      @sock = SSLSocket.new(@sock, context)
+    def start_tls_session
+      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.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
       ssl_socket_connect(@sock, @open_timeout)
-      if context.verify_mode != VERIFY_NONE
+      if ssl_ctx.verify_mode != VERIFY_NONE
         @sock.post_connection_check(@host)
+        @tls_verified = true
       end
     end
 
+    #--
+    # We could get the saslprep method by extending the SASLprep module
+    # directly.  It's done indirectly, so SASLprep can be lazily autoloaded,
+    # because most users won't need it.
+    #++
+    # Delegates to Net::IMAP::StringPrep::SASLprep#saslprep.
+    def self.saslprep(string, **opts)
+      Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
+    end
+
   end
 end
 
@@ -2390,4 +2767,6 @@ require_relative "imap/flags"
 require_relative "imap/response_data"
 require_relative "imap/response_parser"
 require_relative "imap/authenticators"
-require_relative "imap/sasl"
+
+require_relative "imap/deprecated_client_options"
+Net::IMAP.prepend Net::IMAP::DeprecatedClientOptions