🚚 Move SASL.authenticator registry from Net::IMAP

And change `Net::IMAP::SASL.add_authenticator` to be case insensitive
for the mechanism name.

The original methods (`Net::IMAP.authenticator` and
`Net::IMAP.add_authenticator`) both still work, by delegation to the
new methods.  But they have been deprecated.

Author: nevans

lib/net/imap.rb

@@ -1033,7 +1033,7 @@ def starttls(options = {}, verify = true)
     # will be cached.
     #
     def authenticate(mechanism, ...)
-      authenticator = self.class.authenticator(mechanism, ...)
+      authenticator = SASL.authenticator(mechanism, ...)
       send_command("AUTHENTICATE", mechanism) do |resp|
         if resp.instance_of?(ContinuationRequest)
           data = authenticator.process(resp.data.text.unpack("m")[0])

lib/net/imap/authenticators.rb

@@ -1,64 +1,30 @@
 # frozen_string_literal: true
 
-# Registry for SASL authenticators used by Net::IMAP.
+# Backward compatible delegators from Net::IMAP to Net::IMAP::SASL.
 module Net::IMAP::Authenticators
 
-  # Adds an authenticator for Net::IMAP#authenticate to use.  +mechanism+ is the
-  # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-  # implemented by +authenticator+ (for instance, <tt>"PLAIN"</tt>).
-  #
-  # The +authenticator+ must respond to +#new+ (or #call), receiving the
-  # authenticator configuration and return a configured authentication session.
-  # The authenticator session must respond to +#process+, receiving the server's
-  # challenge and returning the client's response.
-  #
-  # See PlainAuthenticator, XOauth2Authenticator, and DigestMD5Authenticator for
-  # examples.
-  def add_authenticator(auth_type, authenticator)
-    authenticators[auth_type] = authenticator
+  # Deprecated.  Use Net::IMAP::SASL.add_authenticator instead.
+  def add_authenticator(...)
+    warn(
+      "%s.%s is deprecated.  Use %s.%s instead." % [
+        Net::IMAP, __method__, Net::IMAP::SASL, __method__
+      ],
+      uplevel: 1
+    )
+    Net::IMAP::SASL.add_authenticator(...)
   end
 
-  # :call-seq:
-  #   authenticator(mechanism, ...)                            -> authenticator
-  #   authenticator(mech, *creds, **props) {|prop, auth| val } -> authenticator
-  #   authenticator(mechanism, authnid, creds, authzid=nil)    -> authenticator
-  #   authenticator(mechanism, **properties)                   -> authenticator
-  #   authenticator(mechanism) {|propname, authctx| value }    -> authenticator
-  #
-  # Builds a new authentication session context for +mechanism+.
-  #
-  # [Note]
-  #   This method is intended for internal use by connection protocol code only.
-  #   Protocol client users should see refer to their client's documentation,
-  #   e.g. Net::IMAP#authenticate for Net::IMAP.
-  #
-  # The call signatures documented for this method are recommendations for
-  # authenticator implementors.  All arguments (other than +mechanism+) are
-  # forwarded to the registered authenticator's +#new+ (or +#call+) method, and
-  # each authenticator must document its own arguments.
-  #
-  # The returned object represents a single authentication exchange and <em>must
-  # not</em> be reused for multiple authentication attempts.
-  def authenticator(mechanism, ...)
-    auth = authenticators.fetch(mechanism.upcase) do
-      raise ArgumentError, 'unknown auth type - "%s"' % mechanism
-    end
-    auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
-  end
-
-  private
-
-  def authenticators
-    @authenticators ||= {}
+  # Deprecated.  Use Net::IMAP::SASL.authenticator instead.
+  def authenticator(...)
+    warn(
+      "%s.%s is deprecated.  Use %s.%s instead." % [
+        Net::IMAP, __method__, Net::IMAP::SASL, __method__
+      ],
+      uplevel: 1
+    )
+    Net::IMAP::SASL.authenticator(...)
   end
 
 end
 
 Net::IMAP.extend Net::IMAP::Authenticators
-
-require_relative "authenticators/plain"
-
-require_relative "authenticators/login"
-require_relative "authenticators/cram_md5"
-require_relative "authenticators/digest_md5"
-require_relative "authenticators/xoauth2"

lib/net/imap/authenticators/cram_md5.rb

@@ -47,5 +47,4 @@ def hmac_md5(text, key)
     return Digest::MD5.hexdigest(k_opad + digest)
   end
 
-  Net::IMAP.add_authenticator "CRAM-MD5", self
 end

lib/net/imap/authenticators/digest_md5.rb

@@ -111,5 +111,4 @@ def qdval(k, v)
     end
   end
 
-  Net::IMAP.add_authenticator "DIGEST-MD5", self
 end

lib/net/imap/authenticators/login.rb

@@ -42,5 +42,4 @@ def initialize(user, password, warn_deprecation: true, **_ignored)
     @state = STATE_USER
   end
 
-  Net::IMAP.add_authenticator "LOGIN", self
 end

lib/net/imap/authenticators/plain.rb

@@ -37,5 +37,4 @@ def initialize(username, password, authzid: nil)
     @authzid  = authzid
   end
 
-  Net::IMAP.add_authenticator "PLAIN", self
 end

lib/net/imap/authenticators/xoauth2.rb

@@ -16,5 +16,4 @@ def build_oauth2_string(user, oauth2_token)
     format("user=%s\1auth=Bearer %s\1\1", user, oauth2_token)
   end
 
-  Net::IMAP.add_authenticator 'XOAUTH2', self
 end

lib/net/imap/sasl.rb

@@ -59,6 +59,25 @@ module SASL
       autoload :ProhibitedCodepoint, stringprep_path
       autoload :BidiStringError,     stringprep_path
 
+      sasl_dir = File.expand_path("sasl", __dir__)
+      autoload :Authenticators,           "#{sasl_dir}/authenticators"
+
+      # Authenticators are all lazy loaded
+      def self.authenticators
+        @authenticators ||= SASL::Authenticators.new.tap do |registry|
+          registry.add_authenticator "Plain",      PlainAuthenticator
+          registry.add_authenticator "XOauth2",    XOauth2Authenticator
+          registry.add_authenticator "Login",      LoginAuthenticator     # deprecated
+          registry.add_authenticator "Cram-MD5",   CramMD5Authenticator   # deprecated
+          registry.add_authenticator "Digest-MD5", DigestMD5Authenticator # deprecated
+        end
+      end
+
+      # Delegates to authenticators.  See Authenticators#authenticator.
+      def self.authenticator(...)     authenticators.authenticator(...) end
+
+      # See SASL::add_authenticator
+      def self.add_authenticator(...) authenticators.add_authenticator(...) end
 
       module_function
 
@@ -69,5 +88,10 @@ def saslprep(string, **opts)
 
     end
   end
-
 end
+
+require_relative "authenticators/plain"
+require_relative "authenticators/login"
+require_relative "authenticators/cram_md5"
+require_relative "authenticators/digest_md5"
+require_relative "authenticators/xoauth2"

lib/net/imap/sasl/authenticators.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Net::IMAP::SASL
+
+  # Registry for SASL mechanism authenticators
+  class Authenticators
+
+    def initialize
+      @authenticators = {}
+    end
+
+    # Returns the hash of SASL mechanism names to registered authenticators.
+    def authenticators; @authenticators.dup end
+
+    # :call-seq:
+    #   add_authenticator(sasl_mechanism_name, authenticator_class)
+    #   add_authenticator(sasl_mechanism_name, authenticator_proc)
+    #
+    # Adds an authenticator for #authenticator to use.  +mechanism+ is the
+    # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+    # implemented by +authenticator+ (for instance, <tt>"PLAIN"</tt>).
+    #
+    # The +authenticator+ must respond to +#new+ (or #call), receiving the
+    # authenticator configuration and return a configured authentication session.
+    # The authenticator session must respond to +#process+, receiving the server's
+    # challenge and returning the client's response.
+    #
+    # See PlainAuthenticator, XOauth2Authenticator, and DigestMD5Authenticator for
+    # examples.
+    def add_authenticator(mechanism, authenticator)
+      @authenticators[mechanism.upcase] = authenticator
+    end
+
+    # :call-seq:
+    #   authenticator(mechanism, ...)                            -> authenticator
+    #   authenticator(mech, *creds, **props) {|prop, auth| val } -> authenticator
+    #   authenticator(mechanism, authnid, creds, authzid=nil)    -> authenticator
+    #   authenticator(mechanism, **properties)                   -> authenticator
+    #   authenticator(mechanism) {|propname, authctx| value }    -> authenticator
+    #
+    # Builds a new authentication session context for +mechanism+.
+    #
+    # [Note]
+    #   This method is intended for internal use by connection protocol code only.
+    #   Protocol client users should see refer to their client's documentation,
+    #   e.g. Net::IMAP#authenticate.
+    #
+    # The call signatures documented for this method are generic recommendations
+    # for authenticators.  All arguments (other than +mechanism+) are forwarded to
+    # the registered authenticator's +#new+ (or +#call+) method, and each
+    # authenticator must document its own arguments.
+    #
+    # The returned object represents a single authentication exchange and <em>must
+    # not</em> be reused for multiple authentication attempts.
+    def authenticator(mechanism, ...)
+      auth = @authenticators.fetch(mechanism.upcase) do
+        raise ArgumentError, 'unknown auth type - "%s"' % mechanism
+      end
+      auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
+    end
+
+  end
+
+end

test/net/imap/test_imap_authenticators.rb

@@ -5,12 +5,18 @@
 
 class IMAPAuthenticatorsTest < Test::Unit::TestCase
 
+  def test_net_imap_authenticator_deprecated
+    assert_warn(/Net::IMAP\.authenticator .+deprecated./) do
+      Net::IMAP.authenticator("PLAIN", "user", "pass")
+    end
+  end
+
   # ----------------------
   # PLAIN
   # ----------------------
 
   def plain(*args, **kwargs, &block)
-    Net::IMAP.authenticator("PLAIN", *args, **kwargs, &block)
+    Net::IMAP::SASL.authenticator("PLAIN", *args, **kwargs, &block)
   end
 
   def test_plain_authenticator_matches_mechanism
@@ -45,7 +51,7 @@ def test_xoauth2
   # ----------------------
 
   def login(*args, warn_deprecation: false, **kwargs, &block)
-    Net::IMAP.authenticator(
+    Net::IMAP::SASL.authenticator(
       "LOGIN", *args, warn_deprecation: warn_deprecation, **kwargs, &block
     )
   end
@@ -56,7 +62,7 @@ def test_login_authenticator_matches_mechanism
 
   def test_login_authenticator_deprecated
     assert_warn(/LOGIN.+deprecated.+PLAIN/) do
-      Net::IMAP.authenticator("LOGIN", "user", "pass")
+      Net::IMAP::SASL.authenticator("LOGIN", "user", "pass")
     end
   end
 
@@ -71,7 +77,7 @@ def test_login_responses
   # ----------------------
 
   def cram_md5(*args, warn_deprecation: false, **kwargs, &block)
-    Net::IMAP.authenticator(
+    Net::IMAP::SASL.authenticator(
       "CRAM-MD5", *args, warn_deprecation: warn_deprecation, **kwargs, &block
     )
   end
@@ -82,7 +88,7 @@ def test_cram_md5_authenticator_matches_mechanism
 
   def test_cram_md5_authenticator_deprecated
     assert_warn(/CRAM-MD5.+deprecated./) do
-      Net::IMAP.authenticator("CRAM-MD5", "user", "pass")
+      Net::IMAP::SASL.authenticator("CRAM-MD5", "user", "pass")
     end
   end
 
@@ -97,7 +103,7 @@ def test_cram_md5_authenticator
   # ----------------------
 
   def digest_md5(*args, warn_deprecation: false, **kwargs, &block)
-    Net::IMAP.authenticator(
+    Net::IMAP::SASL.authenticator(
       "DIGEST-MD5", *args, warn_deprecation: warn_deprecation, **kwargs, &block
     )
   end
@@ -108,7 +114,7 @@ def test_digest_md5_authenticator_matches_mechanism
 
   def test_digest_md5_authenticator_deprecated
     assert_warn(/DIGEST-MD5.+deprecated.+RFC6331/) do
-      Net::IMAP.authenticator("DIGEST-MD5", "user", "pass")
+      Net::IMAP::SASL.authenticator("DIGEST-MD5", "user", "pass")
     end
   end