net-imap 0.4.16 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb20811050c485f7fcde01bb24dbe455026b45cc463efe39353a3f186312a5d5
-  data.tar.gz: 1290933be2c606cb299c75acc7ba59aa3ecdbcad245e776981eb2eb49d3289f3
+  metadata.gz: 2c89d97e842bce303df112c3fbc0f048f20a2ff1dbf3b85bb2314ea0d2e207c5
+  data.tar.gz: 11d6ec196e1e768f61a17b0ce7f385a11eb03e3e92af8ab327ba9a90699ee940
 SHA512:
-  metadata.gz: 857dfd2863abedf53c6adf874a8d6883ea93de91cb01bd0c3ec60ca2279f86e1ae41ddedaccd1329490dddb6dabdce59cddf22699c0792085a5fba2a76184647
-  data.tar.gz: 0766bbf7514aa1c293b18575c47bf02f5eff1c62b69c8cda432aba35d72572607d60588e45ab78a25e5df7f8d7df2fe5c90d965f580c8178171554151ab0c4a0
+  metadata.gz: ca70e20c3c70f4ca57822f70936546adb3129dd7c0771ef2d054b0356ed4f6a994b7453803cc06bd25ebb37dc0ed10f60b5541bc56749dee38a6126264344599
+  data.tar.gz: 2921a79dbdab7bd0476d883c18db50150388d587c711270faac99ad4505574a23e6532fe61a4fb48f51c8bddea6641d96f81d9dcbe245b4d4f4542fcc7418566

data/Gemfile

@@ -13,4 +13,10 @@ gem "rdoc"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 
-gem "benchmark-driver"
+gem "benchmark-driver", require: false
+
+group :test do
+  gem "simplecov",        require: false
+  gem "simplecov-html",   require: false
+  gem "simplecov-json",   require: false
+end

data/lib/net/imap/authenticators.rb

@@ -9,7 +9,7 @@ module Net::IMAP::Authenticators
       "%s.%s is deprecated.  Use %s.%s instead." % [
         Net::IMAP, __method__, Net::IMAP::SASL, __method__
       ],
-      uplevel: 1
+      uplevel: 1, category: :deprecated
     )
     Net::IMAP::SASL.add_authenticator(...)
   end
@@ -20,7 +20,7 @@ module Net::IMAP::Authenticators
       "%s.%s is deprecated.  Use %s.%s instead." % [
         Net::IMAP, __method__, Net::IMAP::SASL, __method__
       ],
-      uplevel: 1
+      uplevel: 1, category: :deprecated
     )
     Net::IMAP::SASL.authenticator(...)
   end

data/lib/net/imap/command_data.rb

@@ -179,6 +179,7 @@ module Net
       end
     end
 
+    # *DEPRECATED*.  Replaced by SequenceSet.
     class MessageSet # :nodoc:
       def send_data(imap, tag)
         imap.__send__(:put_string, format_internal(@data))
@@ -192,6 +193,16 @@ module Net
 
       def initialize(data)
         @data = data
+        warn("DEPRECATED: #{MessageSet} should be replaced with #{SequenceSet}.",
+             uplevel: 1, category: :deprecated)
+        begin
+          # to ensure the input works with SequenceSet, too
+          SequenceSet.new(data)
+        rescue
+          warn "MessageSet input is incompatible with SequenceSet: [%s] %s" % [
+            $!.class, $!.message
+          ]
+        end
       end
 
       def format_internal(data)

data/lib/net/imap/config.rb

@@ -7,10 +7,10 @@ require_relative "config/attr_type_coercion"
 module Net
   class IMAP
 
-    # Net::IMAP::Config stores configuration options for Net::IMAP clients.
-    # The global configuration can be seen at either Net::IMAP.config or
-    # Net::IMAP::Config.global, and the client-specific configuration can be
-    # seen at Net::IMAP#config.
+    # Net::IMAP::Config <em>(available since +v0.4.13+)</em> stores
+    # configuration options for Net::IMAP clients.  The global configuration can
+    # be seen at either Net::IMAP.config or Net::IMAP::Config.global, and the
+    # client-specific configuration can be seen at Net::IMAP#config.
     #
     # When creating a new client, all unhandled keyword arguments to
     # Net::IMAP.new are delegated to Config.new.  Every client has its own
@@ -128,7 +128,7 @@ module Net
       # The global config object.  Also available from Net::IMAP.config.
       def self.global; @global if defined?(@global) end
 
-      # A hash of hard-coded configurations, indexed by version number.
+      # A hash of hard-coded configurations, indexed by version number or name.
       def self.version_defaults; @version_defaults end
       @version_defaults = {}
 
@@ -172,9 +172,16 @@ module Net
       include AttrInheritance
       include AttrTypeCoercion
 
-      # The debug mode (boolean)
+      # The debug mode (boolean).  The default value is +false+.
       #
-      # The default value is +false+.
+      # When #debug is +true+:
+      # * Data sent to and received from the server will be logged.
+      # * ResponseParser will print warnings with extra detail for parse
+      #   errors.  _This may include recoverable errors._
+      # * ResponseParser makes extra assertions.
+      #
+      # *NOTE:* Versioned default configs inherit #debug from Config.global, and
+      # #load_defaults will not override #debug.
       attr_accessor :debug, type: :boolean
 
       # method: debug?
@@ -200,34 +207,84 @@ module Net
       # The default value is +5+ seconds.
       attr_accessor :idle_response_timeout, type: Integer
 
-      # :markup: markdown
-      #
       # Whether to use the +SASL-IR+ extension when the server and \SASL
-      # mechanism both support it.
+      # mechanism both support it.  Can be overridden by the +sasl_ir+ keyword
+      # parameter to Net::IMAP#authenticate.
+      #
+      # <em>(Support for +SASL-IR+ was added in +v0.4.0+.)</em>
+      #
+      # ==== Valid options
       #
-      # See Net::IMAP#authenticate.
+      # [+false+ <em>(original behavior, before support was added)</em>]
+      #   Do not use +SASL-IR+, even when it is supported by the server and the
+      #   mechanism.
       #
-      # | Starting with version | The default value is                     |
-      # |-----------------------|------------------------------------------|
-      # | _original_            | +false+ <em>(extension unsupported)</em> |
-      # | v0.4                  | +true+  <em>(support added)</em>         |
+      # [+true+ <em>(default since +v0.4+)</em>]
+      #   Use +SASL-IR+ when it is supported by the server and the mechanism.
       attr_accessor :sasl_ir, type: :boolean
 
-      # :markup: markdown
+      # Controls the behavior of Net::IMAP#login when the +LOGINDISABLED+
+      # capability is present.  When enforced, Net::IMAP will raise a
+      # LoginDisabledError when that capability is present.
+      #
+      # <em>(Support for +LOGINDISABLED+ was added in +v0.5.0+.)</em>
+      #
+      # ==== Valid options
+      #
+      # [+false+ <em>(original behavior, before support was added)</em>]
+      #   Send the +LOGIN+ command without checking for +LOGINDISABLED+.
+      #
+      # [+:when_capabilities_cached+]
+      #   Enforce the requirement when Net::IMAP#capabilities_cached? is true,
+      #   but do not send a +CAPABILITY+ command to discover the capabilities.
+      #
+      # [+true+ <em>(default since +v0.5+)</em>]
+      #   Only send the +LOGIN+ command if the +LOGINDISABLED+ capability is not
+      #   present.  When capabilities are unknown, Net::IMAP will automatically
+      #   send a +CAPABILITY+ command first before sending +LOGIN+.
+      #
+      attr_accessor :enforce_logindisabled, type: [
+        false, :when_capabilities_cached, true
+      ]
+
+      # Controls the behavior of Net::IMAP#responses when called without any
+      # arguments (+type+ or +block+).
+      #
+      # ==== Valid options
       #
-      # Controls the behavior of Net::IMAP#responses when called without a
-      # block.  Valid options are `:warn`, `:raise`, or
-      # `:silence_deprecation_warning`.
+      # [+:silence_deprecation_warning+ <em>(original behavior)</em>]
+      #   Returns the mutable responses hash (without any warnings).
+      #   <em>This is not thread-safe.</em>
       #
-      # | Starting with version   | The default value is           |
-      # |-------------------------|--------------------------------|
-      # | v0.4.13                 | +:silence_deprecation_warning+ |
-      # | v0.5 <em>(planned)</em> | +:warn+                        |
-      # | _eventually_            | +:raise+                       |
+      # [+:warn+ <em>(default since +v0.5+)</em>]
+      #   Prints a warning and returns the mutable responses hash.
+      #   <em>This is not thread-safe.</em>
+      #
+      # [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
+      #   Returns a frozen copy of the unhandled responses hash, with frozen
+      #   array values.
+      #
+      #   Note that calling IMAP#responses with a +type+ and without a block is
+      #   not configurable and always behaves like +:frozen_dup+.
+      #
+      #   <em>(+:frozen_dup+ config option was added in +v0.4.17+)</em>
+      #
+      # [+:raise+]
+      #   Raise an ArgumentError with the deprecation warning.
+      #
+      # Note: #responses_without_args is an alias for #responses_without_block.
       attr_accessor :responses_without_block, type: [
-        :silence_deprecation_warning, :warn, :raise,
+        :silence_deprecation_warning, :warn, :frozen_dup, :raise,
       ]
 
+      alias responses_without_args  responses_without_block  # :nodoc:
+      alias responses_without_args= responses_without_block= # :nodoc:
+
+      ##
+      # :attr_accessor: responses_without_args
+      #
+      # Alias for responses_without_block
+
       # Creates a new config object and initialize its attribute with +attrs+.
       #
       # If +parent+ is not given, the global config is used by default.
@@ -306,32 +363,36 @@ module Net
         open_timeout: 30,
         idle_response_timeout: 5,
         sasl_ir: true,
-        responses_without_block: :silence_deprecation_warning,
+        enforce_logindisabled: true,
+        responses_without_block: :warn,
       ).freeze
 
       @global = default.new
 
-      version_defaults[0.4] = Config[default.send(:defaults_hash)]
+      version_defaults[:default] = Config[default.send(:defaults_hash)]
+      version_defaults[:current] = Config[:default]
 
-      version_defaults[0] = Config[0.4].dup.update(
+      version_defaults[0] = Config[:current].dup.update(
         sasl_ir: false,
+        responses_without_block: :silence_deprecation_warning,
+        enforce_logindisabled: false,
       ).freeze
       version_defaults[0.0] = Config[0]
       version_defaults[0.1] = Config[0]
       version_defaults[0.2] = Config[0]
       version_defaults[0.3] = Config[0]
 
-      version_defaults[0.5] = Config[0.4].dup.update(
-        responses_without_block: :warn,
+      version_defaults[0.4] = Config[0.3].dup.update(
+        sasl_ir: true,
       ).freeze
 
-      version_defaults[:default] = Config[0.4]
-      version_defaults[:current] = Config[0.4]
-      version_defaults[:next]    = Config[0.5]
+      version_defaults[0.5] = Config[:current]
 
-      version_defaults[:future]  = Config[0.5].dup.update(
-        responses_without_block: :raise,
+      version_defaults[0.6] = Config[0.5].dup.update(
+        responses_without_block: :frozen_dup,
       ).freeze
+      version_defaults[:next] = Config[0.6]
+      version_defaults[:future] = Config[:next]
 
       version_defaults.freeze
     end

data/lib/net/imap/data_encoding.rb

@@ -186,7 +186,7 @@ module Net
 
       # Ensure argument is 'number' or raise DataFormatError
       def ensure_number(num)
-        return if valid_number?(num)
+        return num if valid_number?(num)
 
         msg = "number must be unsigned 32-bit integer: #{num}"
         raise DataFormatError, msg
@@ -194,7 +194,7 @@ module Net
 
       # Ensure argument is 'nz_number' or raise DataFormatError
       def ensure_nz_number(num)
-        return if valid_nz_number?(num)
+        return num if valid_nz_number?(num)
 
         msg = "nz_number must be non-zero unsigned 32-bit integer: #{num}"
         raise DataFormatError, msg
@@ -202,7 +202,7 @@ module Net
 
       # Ensure argument is 'mod_sequence_value' or raise DataFormatError
       def ensure_mod_sequence_value(num)
-        return if valid_mod_sequence_value?(num)
+        return num if valid_mod_sequence_value?(num)
 
         msg = "mod_sequence_value must be unsigned 64-bit integer: #{num}"
         raise DataFormatError, msg

data/lib/net/imap/deprecated_client_options.rb

@@ -83,10 +83,12 @@ module Net
         elsif deprecated.empty?
           super host, port: port_or_options
         elsif deprecated.shift
-          warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1
+          warn("DEPRECATED: Call Net::IMAP.new with keyword options",
+               uplevel: 1, category: :deprecated)
           super host, port: port_or_options, ssl: create_ssl_params(*deprecated)
         else
-          warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1
+          warn("DEPRECATED: Call Net::IMAP.new with keyword options",
+               uplevel: 1, category: :deprecated)
           super host, port: port_or_options, ssl: false
         end
       end
@@ -113,7 +115,8 @@ module Net
         elsif deprecated.first.respond_to?(:to_hash)
           super(**Hash.try_convert(deprecated.first))
         else
-          warn "DEPRECATED: Call Net::IMAP#starttls with keyword options", uplevel: 1
+          warn("DEPRECATED: Call Net::IMAP#starttls with keyword options",
+               uplevel: 1, category: :deprecated)
           super(**create_ssl_params(*deprecated))
         end
       end

data/lib/net/imap/errors.rb

@@ -7,6 +7,12 @@ module Net
     class Error < StandardError
     end
 
+    class LoginDisabledError < Error
+      def initialize(msg = "Remote server has disabled the LOGIN command", ...)
+        super
+      end
+    end
+
     # Error raised when data is in the incorrect format.
     class DataFormatError < Error
     end

data/lib/net/imap/response_data.rb

@@ -939,7 +939,8 @@ module Net
       # for something else?
       #++
       def media_subtype
-        warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
+        warn("media_subtype is obsolete, use subtype instead.\n",
+             uplevel: 1, category: :deprecated)
         return subtype
       end
     end
@@ -984,7 +985,8 @@ module Net
       # generate a warning message to +stderr+, then return
       # the value of +subtype+.
       def media_subtype
-        warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
+        warn("media_subtype is obsolete, use subtype instead.\n",
+             uplevel: 1, category: :deprecated)
         return subtype
       end
     end
@@ -1040,77 +1042,6 @@ module Net
       end
     end
 
-    # BodyTypeAttachment is not used and will be removed in an upcoming release.
-    #
-    # === Bug Analysis
-    #
-    # \IMAP body structures are parenthesized lists and assign their fields
-    # positionally, so missing fields change the interpretation of all
-    # following fields.  Additionally, different body types have a different
-    # number of required fields, followed by optional "extension" fields.
-    #
-    # BodyTypeAttachment was previously returned when a "message/rfc822" part,
-    # which should be sent as <tt>body-type-msg</tt> with ten required fields,
-    # was actually sent as a <tt>body-type-basic</tt> with _seven_ required
-    # fields.
-    #
-    #   basic => type, subtype, param, id, desc, enc, octets, md5=nil,  dsp=nil, lang=nil, loc=nil, *ext
-    #   msg   => type, subtype, param, id, desc, enc, octets, envelope, body,    lines,    md5=nil, ...
-    #
-    # Normally, +envelope+ and +md5+ are incompatible, but Net::IMAP leniently
-    # allowed buggy servers to send +NIL+ for +envelope+.  As a result, when a
-    # server sent a <tt>message/rfc822</tt> part with +NIL+ for +md5+ and a
-    # non-<tt>NIL</tt> +dsp+, Net::IMAP misinterpreted the
-    # <tt>Content-Disposition</tt> as if it were a strange body type.  In all
-    # reported cases, the <tt>Content-Disposition</tt> was "attachment", so
-    # BodyTypeAttachment was created as the workaround.
-    #
-    # === Current behavior
-    #
-    # When interpreted strictly, +envelope+ and +md5+ are incompatible.  So the
-    # current parsing algorithm peeks ahead after it has received the seventh
-    # body field.  If the next token is not the start of an +envelope+, we assume
-    # the server has incorrectly sent us a <tt>body-type-basic</tt> and return
-    # BodyTypeBasic.  As a result, what was previously BodyTypeMessage#body =>
-    # BodyTypeAttachment is now BodyTypeBasic#disposition => ContentDisposition.
-    #
-    class BodyTypeAttachment < Struct.new(:dsp_type, :_unused_, :param)
-      # *invalid for BodyTypeAttachment*
-      def media_type
-        warn(<<~WARN, uplevel: 1)
-          BodyTypeAttachment#media_type is obsolete.  Use dsp_type instead.
-        WARN
-        dsp_type
-      end
-
-      # *invalid for BodyTypeAttachment*
-      def subtype
-        warn("BodyTypeAttachment#subtype is obsolete.\n", uplevel: 1)
-        nil
-      end
-
-      ##
-      # method: dsp_type
-      # :call-seq: dsp_type -> string
-      #
-      # Returns the content disposition type, as defined by
-      # [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
-
-      ##
-      # method: param
-      # :call-seq: param -> hash
-      #
-      # Returns a hash representing parameters of the Content-Disposition
-      # field, as defined by [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
-
-      ##
-      def multipart?
-        return false
-      end
-    end
-
-    deprecate_constant :BodyTypeAttachment
-
     # Net::IMAP::BodyTypeMultipart represents body structures of messages and
     # message parts, when <tt>Content-Type</tt> is <tt>multipart/*</tt>.
     class BodyTypeMultipart < Struct.new(:media_type, :subtype,
@@ -1182,29 +1113,11 @@ module Net
       # generate a warning message to +stderr+, then return
       # the value of +subtype+.
       def media_subtype
-        warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
+        warn("media_subtype is obsolete, use subtype instead.\n",
+             uplevel: 1, category: :deprecated)
         return subtype
       end
     end
 
-    # === Obsolete
-    # BodyTypeExtension is not used and will be removed in an upcoming release.
-    #
-    # >>>
-    #   BodyTypeExtension was (incorrectly) used for <tt>message/*</tt> parts
-    #   (besides <tt>message/rfc822</tt>, which correctly uses BodyTypeMessage).
-    #
-    #   Net::IMAP now (correctly) parses all message types (other than
-    #   <tt>message/rfc822</tt> or <tt>message/global</tt>) as BodyTypeBasic.
-    class BodyTypeExtension < Struct.new(:media_type, :subtype,
-                                         :params, :content_id,
-                                         :description, :encoding, :size)
-      def multipart?
-        return false
-      end
-    end
-
-    deprecate_constant :BodyTypeExtension
-
   end
 end

data/lib/net/imap/response_parser.rb

@@ -1317,31 +1317,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) /

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