net-imap 0.4.17 → 0.5.6

data/lib/net/imap/response_parser/parser_utils.rb

@@ -185,6 +185,11 @@ module Net
           @str[@pos, str.length] == str
         end
 
+        def peek_re?(re)
+          assert_no_lookahead if Net::IMAP.debug
+          re.match?(@str, @pos)
+        end
+
         def peek_re(re)
           assert_no_lookahead if config.debug?
           re.match(@str, @pos)

data/lib/net/imap/response_parser.rb

@@ -13,13 +13,17 @@ module Net
 
       attr_reader :config
 
-      # :call-seq: Net::IMAP::ResponseParser.new -> Net::IMAP::ResponseParser
+      # Creates a new ResponseParser.
+      #
+      # When +config+ is frozen or global, the parser #config inherits from it.
+      # Otherwise, +config+ will be used directly.
       def initialize(config: Config.global)
         @str = nil
         @pos = nil
         @lex_state = nil
         @token = nil
         @config = Config[config]
+        @config = @config.new if @config == Config.global || @config.frozen?
       end
 
       # :call-seq:
@@ -321,6 +325,24 @@ module Net
         SEQUENCE_SET      = /#{SEQUENCE_SET_ITEM}(?:,#{SEQUENCE_SET_ITEM})*/n
         SEQUENCE_SET_STR  = /\A#{SEQUENCE_SET}\z/n
 
+        # partial-range-first = nz-number ":" nz-number
+        #     ;; Request to search from oldest (lowest UIDs) to
+        #     ;; more recent messages.
+        #     ;; A range 500:400 is the same as 400:500.
+        #     ;; This is similar to <seq-range> from [RFC3501]
+        #     ;; but cannot contain "*".
+        PARTIAL_RANGE_FIRST = /\A(#{NZ_NUMBER}):(#{NZ_NUMBER})\z/n
+
+        # partial-range-last  = MINUS nz-number ":" MINUS nz-number
+        #     ;; Request to search from newest (highest UIDs) to
+        #     ;; oldest messages.
+        #     ;; A range -500:-400 is the same as -400:-500.
+        PARTIAL_RANGE_LAST  = /\A(-#{NZ_NUMBER}):(-#{NZ_NUMBER})\z/n
+
+        # partial-range     = partial-range-first / partial-range-last
+        PARTIAL_RANGE       = Regexp.union(PARTIAL_RANGE_FIRST,
+                                           PARTIAL_RANGE_LAST)
+
         # RFC3501:
         #   literal          = "{" number "}" CRLF *CHAR8
         #                        ; Number represents the number of CHAR8s
@@ -716,7 +738,7 @@ module Net
         when "EXISTS"     then mailbox_data__exists      # RFC3501, RFC9051
         when "ESEARCH"    then esearch_response          # RFC4731, RFC9051, etc
         when "VANISHED"   then expunged_resp             # RFC7162
-        when "UIDFETCH"   then uidfetch_resp             # (draft) UIDONLY
+        when "UIDFETCH"   then uidfetch_resp             # RFC9586
         when "SEARCH"     then mailbox_data__search      # RFC3501 (obsolete)
         when "CAPABILITY" then capability_data__untagged # RFC3501, RFC9051
         when "FLAGS"      then mailbox_data__flags       # RFC3501, RFC9051
@@ -769,9 +791,6 @@ module Net
       def response_data__ignored; response_data__unhandled(IgnoredResponse) end
       alias response_data__noop     response_data__ignored
 
-      alias esearch_response        response_data__unhandled
-      alias expunged_resp           response_data__unhandled
-      alias uidfetch_resp           response_data__unhandled
       alias listrights_data         response_data__unhandled
       alias myrights_data           response_data__unhandled
       alias metadata_resp           response_data__unhandled
@@ -832,6 +851,14 @@ module Net
         UntaggedResponse.new(name, data, @str)
       end
 
+      #   uidfetch-resp = uniqueid SP "UIDFETCH" SP msg-att
+      def uidfetch_resp
+        uid  = uniqueid;         SP!
+        name = label "UIDFETCH"; SP!
+        data = UIDFetchData.new(uid, msg_att(uid))
+        UntaggedResponse.new(name, data, @str)
+      end
+
       def response_data__simple_numeric
         data = nz_number; SP!
         name = tagged_ext_label
@@ -842,6 +869,20 @@ module Net
       alias mailbox_data__exists  response_data__simple_numeric
       alias mailbox_data__recent  response_data__simple_numeric
 
+      # The name for this is confusing, because it *replaces* EXPUNGE
+      # >>>
+      #   expunged-resp       =  "VANISHED" [SP "(EARLIER)"] SP known-uids
+      def expunged_resp
+        name    = label "VANISHED"; SP!
+        earlier = if lpar? then label("EARLIER"); rpar; SP!; true else false end
+        uids    = known_uids
+        data    = VanishedData[uids, earlier]
+        UntaggedResponse.new name, data, @str
+      end
+
+      # TODO: replace with uid_set
+      alias known_uids sequence_set
+
       # RFC3501 & RFC9051:
       #   msg-att         = "(" (msg-att-dynamic / msg-att-static)
       #                      *(SP (msg-att-dynamic / msg-att-static)) ")"
@@ -1317,31 +1358,19 @@ module Net
       #   header-fld-name = astring
       #
       # NOTE: Previously, Net::IMAP recreated the raw original source string.
-      # Now, it grabs the raw encoded value using @str and @pos.  A future
-      # version may simply return the decoded astring value.  Although that is
-      # technically incompatible, it should almost never make a difference: all
-      # standard header field names are valid atoms:
+      # Now, it returns the decoded astring value.  Although this is technically
+      # incompatible, it should almost never make a difference: all standard
+      # header field names are valid atoms:
       #
       # https://www.iana.org/assignments/message-headers/message-headers.xhtml
       #
-      # Although RFC3501 allows any astring, RFC5322-valid header names are one
-      # or more of the printable US-ASCII characters, except SP and colon.  So
-      # empty string isn't valid, and literals aren't needed and should not be
-      # used.  This is explicitly unchanged by [I18N-HDRS] (RFC6532).
-      #
-      # RFC5233:
+      # See also RFC5233:
       #     optional-field  =   field-name ":" unstructured CRLF
       #     field-name      =   1*ftext
       #     ftext           =   %d33-57 /          ; Printable US-ASCII
       #                         %d59-126           ;  characters not including
       #                                            ;  ":".
-      def header_fld_name
-        assert_no_lookahead
-        start = @pos
-        astring
-        end_pos = @token ? @pos - 1 : @pos
-        @str[start...end_pos]
-      end
+      alias header_fld_name astring
 
       # mailbox-data    =  "FLAGS" SP flag-list / "LIST" SP mailbox-list /
       #                    "LSUB" SP mailbox-list / "SEARCH" *(SP nz-number) /
@@ -1480,6 +1509,111 @@ module Net
       end
       alias sort_data mailbox_data__search
 
+      # esearch-response  = "ESEARCH" [search-correlator] [SP "UID"]
+      #                      *(SP search-return-data)
+      #                    ;; Note that SEARCH and ESEARCH responses
+      #                    ;; SHOULD be mutually exclusive,
+      #                    ;; i.e., only one of the response types
+      #                    ;; should be
+      #                    ;; returned as a result of a command.
+      # esearch-response  = "ESEARCH" [search-correlator] [SP "UID"]
+      #                     *(SP search-return-data)
+      #                   ; ESEARCH response replaces SEARCH response
+      #                   ; from IMAP4rev1.
+      # search-correlator  = SP "(" "TAG" SP tag-string ")"
+      def esearch_response
+        name = label("ESEARCH")
+        tag  = search_correlator if peek_str?(" (")
+        uid  = peek_re?(/\G UID\b/i) && (SP!; label("UID"); true)
+        data = []
+        data << search_return_data while SP?
+        esearch = ESearchResult.new(tag, uid, data)
+        UntaggedResponse.new(name, esearch, @str)
+      end
+
+      # From RFC4731 (ESEARCH):
+      #   search-return-data    = "MIN" SP nz-number /
+      #                           "MAX" SP nz-number /
+      #                           "ALL" SP sequence-set /
+      #                           "COUNT" SP number /
+      #                           search-ret-data-ext
+      #                           ; All return data items conform to
+      #                           ; search-ret-data-ext syntax.
+      #   search-ret-data-ext   = search-modifier-name SP search-return-value
+      #   search-modifier-name  = tagged-ext-label
+      #   search-return-value   = tagged-ext-val
+      #
+      # From RFC4731 (ESEARCH):
+      #   search-return-data    =/ "MODSEQ" SP mod-sequence-value
+      #
+      # From RFC9394 (PARTIAL):
+      #   search-return-data  =/ ret-data-partial
+      #
+      def search_return_data
+        label = search_modifier_name; SP!
+        value =
+          case label
+          when "MIN"        then nz_number
+          when "MAX"        then nz_number
+          when "ALL"        then sequence_set
+          when "COUNT"      then number
+          when "MODSEQ"     then mod_sequence_value         # RFC7162: CONDSTORE
+          when "PARTIAL"    then ret_data_partial__value    # RFC9394: PARTIAL
+          else search_return_value
+          end
+        [label, value]
+      end
+
+      # From RFC5267 (CONTEXT=SEARCH, CONTEXT=SORT) and RFC9394 (PARTIAL):
+      #   ret-data-partial    = "PARTIAL"
+      #                         SP "(" partial-range SP partial-results ")"
+      def ret_data_partial__value
+        lpar
+        range   = partial_range;   SP!
+        results = partial_results
+        rpar
+        ESearchResult::PartialResult.new(range, results)
+      end
+
+      # partial-range       = partial-range-first / partial-range-last
+      # tagged-ext-simple   =/ partial-range-last
+      def partial_range
+        case (str = atom)
+        when Patterns::PARTIAL_RANGE_FIRST, Patterns::PARTIAL_RANGE_LAST
+          min, max = [Integer($1), Integer($2)].minmax
+          min..max
+        else
+          parse_error("unexpected atom %p, expected partial-range", str)
+        end
+      end
+
+      # partial-results     = sequence-set / "NIL"
+      #     ;; <sequence-set> from [RFC3501].
+      #     ;; NIL indicates that no results correspond to
+      #     ;; the requested range.
+      def partial_results; NIL? ? nil : sequence_set end
+
+      # search-modifier-name = tagged-ext-label
+      alias search_modifier_name tagged_ext_label
+
+      # search-return-value = tagged-ext-val
+      #                     ; Data for the returned search option.
+      #                     ; A single "nz-number"/"number"/"number64" value
+      #                     ; can be returned as an atom (i.e., without
+      #                     ; quoting).  A sequence-set can be returned
+      #                     ; as an atom as well.
+      def search_return_value; ExtensionData.new(tagged_ext_val) end
+
+      # search-correlator  = SP "(" "TAG" SP tag-string ")"
+      def search_correlator
+        SP!; lpar; label("TAG"); SP!; tag = tag_string; rpar
+        tag
+      end
+
+      # tag-string      = astring
+      #                   ; <tag> represented as <astring>
+      alias tag_string astring
+
       # RFC5256: THREAD
       #   thread-data     = "THREAD" [SP 1*thread-list]
       def thread_data
@@ -1812,6 +1946,9 @@ module Net
       #
       # RFC8474: OBJECTID
       #   resp-text-code   =/ "MAILBOXID" SP "(" objectid ")"
+      #
+      # RFC9586: UIDONLY
+      #   resp-text-code   =/ "UIDREQUIRED"
       def resp_text_code
         name = resp_text_code__name
         data =
@@ -1834,6 +1971,7 @@ module Net
           when "HIGHESTMODSEQ"      then SP!; mod_sequence_value   # CONDSTORE
           when "MODIFIED"           then SP!; sequence_set         # CONDSTORE
           when "MAILBOXID"          then SP!; parens__objectid     # RFC8474: OBJECTID
+          when "UIDREQUIRED"        then                           # RFC9586: UIDONLY
           else
             SP? and text_chars_except_rbra
           end
@@ -1863,11 +2001,10 @@ module Net
       #
       # n.b, uniqueid ⊂ uid-set.  To avoid inconsistent return types, we always
       # match uid_set even if that returns a single-member array.
-      #
       def resp_code_apnd__data
         validity = number; SP!
         dst_uids = uid_set # uniqueid ⊂ uid-set
-        UIDPlusData.new(validity, nil, dst_uids)
+        AppendUID(validity, dst_uids)
       end
 
       # already matched:  "COPYUID"
@@ -1877,7 +2014,25 @@ module Net
         validity = number;  SP!
         src_uids = uid_set; SP!
         dst_uids = uid_set
-        UIDPlusData.new(validity, src_uids, dst_uids)
+        CopyUID(validity, src_uids, dst_uids)
+      end
+
+      def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end
+      def CopyUID(...)   DeprecatedUIDPlus(...) || CopyUIDData.new(...)   end
+
+      # TODO: remove this code in the v0.6.0 release
+      def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids)
+        return unless config.parser_use_deprecated_uidplus_data
+        compact_uid_sets = [src_uids, dst_uids].compact
+        count = compact_uid_sets.map { _1.count_with_duplicates }.max
+        max   = config.parser_max_deprecated_uidplus_data_size
+        if count <= max
+          src_uids &&= src_uids.each_ordered_number.to_a
+          dst_uids   = dst_uids.each_ordered_number.to_a
+          UIDPlusData.new(validity, src_uids, dst_uids)
+        elsif config.parser_use_deprecated_uidplus_data != :up_to_max_size
+          parse_error("uid-set is too large: %d > %d", count, max)
+        end
       end
 
       ADDRESS_REGEXP = /\G
@@ -2003,15 +2158,9 @@ module Net
       #      uniqueid        = nz-number
       #                          ; Strictly ascending
       def uid_set
-        token = match(T_NUMBER, T_ATOM)
-        case token.symbol
-        when T_NUMBER then [Integer(token.value)]
-        when T_ATOM
-          token.value.split(",").flat_map {|range|
-            range = range.split(":").map {|uniqueid| Integer(uniqueid) }
-            range.size == 1 ? range : Range.new(range.min, range.max).to_a
-          }
-        end
+        set = sequence_set
+        parse_error("uid-set cannot contain '*'") if set.include_star?
+        set
       end
 
       def nil_atom

data/lib/net/imap/sasl/anonymous_authenticator.rb

@@ -5,7 +5,7 @@ module Net
     module SASL
 
       # Authenticator for the "+ANONYMOUS+" SASL mechanism, as specified by
-      # RFC-4505[https://tools.ietf.org/html/rfc4505].  See
+      # RFC-4505[https://www.rfc-editor.org/rfc/rfc4505].  See
       # Net::IMAP#authenticate.
       class AnonymousAuthenticator
 
@@ -13,7 +13,7 @@ module Net
         # characters in length.
         #
         # If it contains an "@" sign, the message must be a valid email address
-        # (+addr-spec+ from RFC-2822[https://tools.ietf.org/html/rfc2822]).
+        # (+addr-spec+ from RFC-2822[https://www.rfc-editor.org/rfc/rfc2822]).
         # Email syntax is _not_ validated by AnonymousAuthenticator.
         #
         # Otherwise, it can be any UTF8 string which is permitted by the
@@ -25,7 +25,7 @@ module Net
         #   new(anonymous_message:  "", **) -> authenticator
         #
         # Creates an Authenticator for the "+ANONYMOUS+" SASL mechanism, as
-        # specified in RFC-4505[https://tools.ietf.org/html/rfc4505].  To use
+        # specified in RFC-4505[https://www.rfc-editor.org/rfc/rfc4505].  To use
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #

data/lib/net/imap/sasl/authentication_exchange.rb

@@ -4,44 +4,76 @@ module Net
   class IMAP
     module SASL
 
-      # This API is *experimental*, and may change.
+      # AuthenticationExchange is used internally by Net::IMAP#authenticate.
+      # But the API is still *experimental*, and may change.
       #
       # TODO: catch exceptions in #process and send #cancel_response.
       # TODO: raise an error if the command succeeds after being canceled.
       # TODO: use with more clients, to verify the API can accommodate them.
+      # TODO: pass ClientAdapter#service to SASL.authenticator
       #
-      # Create an AuthenticationExchange from a client adapter and a mechanism
-      # authenticator:
-      #     def authenticate(mechanism, ...)
-      #       authenticator = SASL.authenticator(mechanism, ...)
-      #       SASL::AuthenticationExchange.new(
-      #         sasl_adapter, mechanism, authenticator
-      #       ).authenticate
-      #     end
-      #
-      #     private
+      # An AuthenticationExchange represents a single attempt to authenticate
+      # a SASL client to a SASL server.  It is created from a client adapter, a
+      # mechanism name, and a mechanism authenticator.  When #authenticate is
+      # called, it will send the appropriate authenticate command to the server,
+      # returning the client response on success and raising an exception on
+      # failure.
       #
-      #     def sasl_adapter = MyClientAdapter.new(self, &method(:send_command))
+      # In most cases, the client will not need to use
+      # SASL::AuthenticationExchange directly at all.  Instead, use
+      # SASL::ClientAdapter#authenticate.  If customizations are needed, the
+      # custom client adapter is probably the best place for that code.
       #
-      # Or delegate creation of the authenticator to ::build:
       #     def authenticate(...)
-      #       SASL::AuthenticationExchange.build(sasl_adapter, ...)
-      #         .authenticate
+      #       MyClient::SASLAdapter.new(self).authenticate(...)
       #     end
       #
-      # As a convenience, ::authenticate combines ::build and #authenticate:
+      # SASL::ClientAdapter#authenticate delegates to ::authenticate, like so:
+      #
       #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
       #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
       #     end
       #
-      # Likewise, ClientAdapter#authenticate delegates to #authenticate:
-      #     def authenticate(...) = sasl_adapter.authenticate(...)
+      # ::authenticate simply delegates to ::build and #authenticate, like so:
+      #
+      #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       SASL::AuthenticationExchange
+      #         .build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # And ::build delegates to SASL.authenticator and ::new, like so:
+      #
+      #     def authenticate(mechanism, ...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange
+      #         .new(sasl_adapter, mechanism, authenticator)
+      #         .authenticate
+      #     end
       #
       class AuthenticationExchange
         # Convenience method for <tt>build(...).authenticate</tt>
+        #
+        # See also: SASL::ClientAdapter#authenticate
         def self.authenticate(...) build(...).authenticate end
 
-        # Use +registry+ to override the global Authenticators registry.
+        # Convenience method to combine the creation of a new authenticator and
+        # a new Authentication exchange.
+        #
+        # +client+ must be an instance of SASL::ClientAdapter.
+        #
+        # +mechanism+ must be a SASL mechanism name, as a string or symbol.
+        #
+        # +sasl_ir+ allows or disallows sending an "initial response", depending
+        # also on whether the server capabilities, mechanism authenticator, and
+        # client adapter all support it.  Defaults to +true+.
+        #
+        # +mechanism+, +args+, +kwargs+, and +block+ are all forwarded to
+        # SASL.authenticator.  Use the +registry+ kwarg to override the global
+        # SASL::Authenticators registry.
         def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block)
           authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block)
           new(client, mechanism, authenticator, sasl_ir: sasl_ir)
@@ -51,7 +83,7 @@ module Net
 
         def initialize(client, mechanism, authenticator, sasl_ir: true)
           @client = client
-          @mechanism = -mechanism.to_s.upcase.tr(?_, ?-)
+          @mechanism = Authenticators.normalize_name(mechanism)
           @authenticator = authenticator
           @sasl_ir = sasl_ir
           @processed = false

data/lib/net/imap/sasl/authenticators.rb

@@ -21,6 +21,10 @@ module Net::IMAP::SASL
   # ScramSHA1Authenticator for examples.
   class Authenticators
 
+    # Normalize the mechanism name as an uppercase string, with underscores
+    # converted to dashes.
+    def self.normalize_name(mechanism) -(mechanism.to_s.upcase.tr(?_, ?-)) end
+
     # Create a new Authenticators registry.
     #
     # This class is usually not instantiated directly.  Use SASL.authenticators
@@ -65,7 +69,6 @@ module Net::IMAP::SASL
     # lazily loaded from <tt>Net::IMAP::SASL::#{name}Authenticator</tt> (case is
     # preserved and non-alphanumeric characters are removed..
     def add_authenticator(name, authenticator = nil)
-      key = -name.to_s.upcase.tr(?_, ?-)
       authenticator ||= begin
         class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
         auth_class = nil
@@ -74,17 +77,18 @@ module Net::IMAP::SASL
           auth_class.new(*creds, **props, &block)
         }
       end
+      key = Authenticators.normalize_name(name)
       @authenticators[key] = authenticator
     end
 
     # Removes the authenticator registered for +name+
     def remove_authenticator(name)
-      key = -name.to_s.upcase.tr(?_, ?-)
+      key = Authenticators.normalize_name(name)
       @authenticators.delete(key)
     end
 
     def mechanism?(name)
-      key = -name.to_s.upcase.tr(?_, ?-)
+      key = Authenticators.normalize_name(name)
       @authenticators.key?(key)
     end
 
@@ -105,7 +109,7 @@ module Net::IMAP::SASL
     #   only.  Protocol client users should see refer to their client's
     #   documentation, e.g. Net::IMAP#authenticate.
     def authenticator(mechanism, ...)
-      key = -mechanism.to_s.upcase.tr(?_, ?-)
+      key = Authenticators.normalize_name(mechanism)
       auth = @authenticators.fetch(key) do
         raise ArgumentError, 'unknown auth type - "%s"' % key
       end

data/lib/net/imap/sasl/client_adapter.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module Net
   class IMAP
     module SASL
@@ -8,42 +10,76 @@ module Net
       #
       # TODO: use with more clients, to verify the API can accommodate them.
       #
-      # An abstract base class for implementing a SASL authentication exchange.
-      # Different clients will each have their own adapter subclass, overridden
-      # to match their needs.
+      # Represents the client to a SASL::AuthenticationExchange.  By default,
+      # most methods simply delegate to #client.  Clients should subclass
+      # SASL::ClientAdapter and override methods as needed to match the
+      # semantics of this API to their API.
       #
-      # Although the default implementations _may_ be sufficient, subclasses
-      # will probably need to override some methods.  Additionally, subclasses
-      # may need to include a protocol adapter mixin, if the default
+      # Subclasses should also include a protocol adapter mixin when the default
       # ProtocolAdapters::Generic isn't sufficient.
+      #
+      # === Protocol Requirements
+      #
+      # {RFC4422 §4}[https://www.rfc-editor.org/rfc/rfc4422.html#section-4]
+      # lists requirements for protocol specifications to offer SASL.  Where
+      # possible, ClientAdapter delegates the handling of these requirements to
+      # SASL::ProtocolAdapters.
       class ClientAdapter
+        extend Forwardable
+
         include ProtocolAdapters::Generic
 
-        attr_reader :client, :command_proc
+        # The client that handles communication with the protocol server.
+        #
+        # Most ClientAdapter methods are simply delegated to #client by default.
+        attr_reader :client
 
         # +command_proc+ can used to avoid exposing private methods on #client.
-        # It should run a command with the arguments sent to it, yield each
-        # continuation payload, respond to the server with the result of each
-        # yield, and return the result.  Non-successful results *MUST* raise an
-        # exception.  Exceptions in the block *MUST* cause the command to fail.
+        # It's value is set by the block that is passed to ::new, and it is used
+        # by the default implementation of #run_command.  Subclasses that
+        # override #run_command may use #command_proc for any other purpose they
+        # find useful.
         #
-        # Subclasses that override #run_command may use #command_proc for
-        # other purposes.
+        # In the default implementation of #run_command, command_proc is called
+        # with the protocols authenticate +command+ name, the +mechanism+ name,
+        # an _optional_ +initial_response+ argument, and a +continuations+
+        # block.  command_proc must run the protocol command with the arguments
+        # sent to it, _yield_ the payload of each continuation, respond to the
+        # continuation with the result of each _yield_, and _return_ the
+        # command's successful result.  Non-successful results *MUST* raise
+        # an exception.
+        attr_reader :command_proc
+
+        # By default, this simply sets the #client and #command_proc attributes.
+        # Subclasses may override it, for example: to set the appropriate
+        # command_proc automatically.
         def initialize(client, &command_proc)
           @client, @command_proc = client, command_proc
         end
 
-        # Delegates to AuthenticationExchange.authenticate.
+        # Attempt to authenticate #client to the server.
+        #
+        # By default, this simply delegates to
+        # AuthenticationExchange.authenticate.
         def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
 
-        # Do the protocol and server both support an initial response?
-        def sasl_ir_capable?; client.sasl_ir_capable? end
+        ##
+        # method: sasl_ir_capable?
+        # Do the protocol, server, and client all support an initial response?
+        def_delegator :client, :sasl_ir_capable?
 
-        # Does the server advertise support for the mechanism?
-        def auth_capable?(mechanism); client.auth_capable?(mechanism) end
+        ##
+        # method: auth_capable?
+        # call-seq: auth_capable?(mechanism)
+        #
+        # Does the server advertise support for the +mechanism+?
+        def_delegator :client, :auth_capable?
 
-        # Runs the authenticate command with +mechanism+ and +initial_response+.
-        # When +initial_response+ is nil, an initial response must NOT be sent.
+        # Calls command_proc with +command_name+ (see
+        # SASL::ProtocolAdapters::Generic#command_name),
+        # +mechanism+, +initial_response+, and a +continuations_handler+ block.
+        # The +initial_response+ is optional; when it's nil, it won't be sent to
+        # command_proc.
         #
         # Yields each continuation payload, responds to the server with the
         # result of each yield, and returns the result.  Non-successful results
@@ -51,21 +87,36 @@ module Net
         # command to fail.
         #
         # Subclasses that override this may use #command_proc differently.
-        def run_command(mechanism, initial_response = nil, &block)
+        def run_command(mechanism, initial_response = nil, &continuations_handler)
           command_proc or raise Error, "initialize with block or override"
           args = [command_name, mechanism, initial_response].compact
-          command_proc.call(*args, &block)
+          command_proc.call(*args, &continuations_handler)
         end
 
+        ##
+        # method: host
+        # The hostname to which the client connected.
+        def_delegator :client, :host
+
+        ##
+        # method: port
+        # The destination port to which the client connected.
+        def_delegator :client, :port
+
         # Returns an array of server responses errors raised by run_command.
         # Exceptions in this array won't drop the connection.
         def response_errors; [] end
 
-        # Drop the connection gracefully.
-        def drop_connection;  client.drop_connection end
+        ##
+        # method: drop_connection
+        # Drop the connection gracefully, sending a "LOGOUT" command as needed.
+        def_delegator :client, :drop_connection
+
+        ##
+        # method: drop_connection!
+        # Drop the connection abruptly, closing the socket without logging out.
+        def_delegator :client, :drop_connection!
 
-        # Drop the connection abruptly.
-        def drop_connection!; client.drop_connection! end
       end
     end
   end