📚🚚 Reorder SASL files and update visibility

The rdoc output is improved simply by making some constants private and
`#initialize` public,

Except for changing visibility, no code was changed (only rearranged).

Author: nevans

lib/net/imap/sasl/anonymous_authenticator.rb

@@ -9,6 +9,17 @@ module SASL
       # Net::IMAP#authenticate.
       class AnonymousAuthenticator
 
+        # An optional token sent for the +ANONYMOUS+ mechanism., up to 255 UTF-8
+        # 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]).
+        # Email syntax is _not_ validated by AnonymousAuthenticator.
+        #
+        # Otherwise, it can be any UTF8 string which is permitted by the
+        # StringPrep::Trace profile.
+        attr_reader :anonymous_message
+
         # :call-seq:
         #   new(anonymous_message = "", **) -> authenticator
         #   new(anonymous_message:  "", **) -> authenticator
@@ -31,17 +42,6 @@ def initialize(anon_msg = nil, anonymous_message: nil, **)
           end
         end
 
-        # An optional token sent for the +ANONYMOUS+ mechanism., up to 255 UTF-8
-        # 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]).
-        # Email syntax is _not_ validated by AnonymousAuthenticator.
-        #
-        # Otherwise, it can be any UTF8 string which is permitted by the
-        # StringPrep::Trace profile.
-        attr_reader :anonymous_message
-
         # :call-seq:
         #   initial_response? -> true
         #

lib/net/imap/sasl/cram_md5_authenticator.rb

@@ -14,13 +14,6 @@
 # of cleartext and recommends TLS version 1.2 or greater be used for all
 # traffic.  With TLS +CRAM-MD5+ is okay, but so is +PLAIN+
 class Net::IMAP::SASL::CramMD5Authenticator
-  def process(challenge)
-    digest = hmac_md5(challenge, @password)
-    return @user + " " + digest
-  end
-
-  private
-
   def initialize(user, password, warn_deprecation: true, **_ignored)
     if warn_deprecation
       warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
@@ -30,6 +23,13 @@ def initialize(user, password, warn_deprecation: true, **_ignored)
     @password = password
   end
 
+  def process(challenge)
+    digest = hmac_md5(challenge, @password)
+    return @user + " " + digest
+  end
+
+  private
+
   def hmac_md5(text, key)
     if key.length > 64
       key = Digest::MD5.digest(key)

lib/net/imap/sasl/digest_md5_authenticator.rb

@@ -9,6 +9,21 @@
 # {RFC6331}[https://tools.ietf.org/html/rfc6331] and should not be relied on for
 # security.  It is included for compatibility with existing servers.
 class Net::IMAP::SASL::DigestMD5Authenticator
+  STAGE_ONE = :stage_one
+  STAGE_TWO = :stage_two
+  private_constant :STAGE_ONE, :STAGE_TWO
+
+  def initialize(user, password, authname = nil, warn_deprecation: true)
+    if warn_deprecation
+      warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."
+      # TODO: recommend SCRAM instead.
+    end
+    require "digest/md5"
+    require "strscan"
+    @user, @password, @authname = user, password, authname
+    @nc, @stage = {}, STAGE_ONE
+  end
+
   def process(challenge)
     case @stage
     when STAGE_ONE
@@ -74,23 +89,8 @@ def process(challenge)
     end
   end
 
-  def initialize(user, password, authname = nil, warn_deprecation: true)
-    if warn_deprecation
-      warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."
-      # TODO: recommend SCRAM instead.
-    end
-    require "digest/md5"
-    require "strscan"
-    @user, @password, @authname = user, password, authname
-    @nc, @stage = {}, STAGE_ONE
-  end
-
-
   private
 
-  STAGE_ONE = :stage_one
-  STAGE_TWO = :stage_two
-
   def nc(nonce)
     if @nc.has_key? nonce
       @nc[nonce] = @nc[nonce] + 1

lib/net/imap/sasl/external_authenticator.rb

@@ -12,6 +12,12 @@ module SASL
       # established external to SASL, for example by TLS certificate or IPsec.
       class ExternalAuthenticator
 
+        # Authorization identity: an identity to act as or on behalf of.
+        #
+        # If not explicitly provided, the server defaults to using the identity
+        # that was authenticated by the external credentials.
+        attr_reader :authzid
+
         # :call-seq:
         #   new(authzid: nil, **) -> authenticator
         #
@@ -30,12 +36,6 @@ def initialize(authzid: nil)
           end
         end
 
-        # Authorization identity: an identity to act as or on behalf of.
-        #
-        # If not explicitly provided, the server defaults to using the identity
-        # that was authenticated by the external credentials.
-        attr_reader :authzid
-
         # :call-seq:
         #   initial_response? -> true
         #

lib/net/imap/sasl/login_authenticator.rb

@@ -18,20 +18,9 @@
 # {draft-murchison-sasl-login}[https://www.iana.org/go/draft-murchison-sasl-login]
 # for both specification and deprecation.
 class Net::IMAP::SASL::LoginAuthenticator
-  def process(data)
-    case @state
-    when STATE_USER
-      @state = STATE_PASSWORD
-      return @user
-    when STATE_PASSWORD
-      return @password
-    end
-  end
-
-  private
-
   STATE_USER = :USER
   STATE_PASSWORD = :PASSWORD
+  private_constant :STATE_USER, :STATE_PASSWORD
 
   def initialize(user, password, warn_deprecation: true, **_ignored)
     if warn_deprecation
@@ -42,4 +31,13 @@ def initialize(user, password, warn_deprecation: true, **_ignored)
     @state = STATE_USER
   end
 
+  def process(data)
+    case @state
+    when STATE_USER
+      @state = STATE_PASSWORD
+      return @user
+    when STATE_PASSWORD
+      return @password
+    end
+  end
 end

lib/net/imap/sasl/oauthbearer_authenticator.rb

@@ -14,35 +14,6 @@ module SASL
       class OAuthAuthenticator
         include GS2Header
 
-        # Creates an RFC7628[https://tools.ietf.org/html/rfc7628] OAuth
-        # authenticator.
-        #
-        # === Options
-        #
-        # See child classes for required configuration parameter(s).  The
-        # following parameters are all optional, but protocols or servers may
-        # add requirements for #authzid, #host, #port, or any other parameter.
-        #
-        # * #authzid ― Identity to act as or on behalf of.
-        # * #host — Hostname to which the client connected.
-        # * #port — Service port to which the client connected.
-        # * #mthd — HTTP method
-        # * #path — HTTP path data
-        # * #post — HTTP post data
-        # * #qs   — HTTP query string
-        #
-        def initialize(authzid: nil, host: nil, port: nil,
-                       mthd: nil, path: nil, post: nil, qs: nil, **)
-          @authzid = authzid
-          @host    = host
-          @port    = port
-          @mthd    = mthd
-          @path    = path
-          @post    = post
-          @qs      = qs
-          @done    = false
-        end
-
         # Authorization identity: an identity to act as or on behalf of.
         #
         # If no explicit authorization identity is provided, it is usually
@@ -73,6 +44,45 @@ def initialize(authzid: nil, host: nil, port: nil,
         # this may hold information about the failure reason, as JSON.
         attr_reader :last_server_response
 
+        # Creates an RFC7628[https://tools.ietf.org/html/rfc7628] OAuth
+        # authenticator.
+        #
+        # === Options
+        #
+        # See child classes for required configuration parameter(s).  The
+        # following parameters are all optional, but protocols or servers may
+        # add requirements for #authzid, #host, #port, or any other parameter.
+        #
+        # * #authzid ― Identity to act as or on behalf of.
+        # * #host — Hostname to which the client connected.
+        # * #port — Service port to which the client connected.
+        # * #mthd — HTTP method
+        # * #path — HTTP path data
+        # * #post — HTTP post data
+        # * #qs   — HTTP query string
+        #
+        def initialize(authzid: nil, host: nil, port: nil,
+                       mthd: nil, path: nil, post: nil, qs: nil, **)
+          @authzid = authzid
+          @host    = host
+          @port    = port
+          @mthd    = mthd
+          @path    = path
+          @post    = post
+          @qs      = qs
+          @done    = false
+        end
+
+        # The {RFC7628 §3.1}[https://www.rfc-editor.org/rfc/rfc7628#section-3.1]
+        # formatted response.
+        def initial_client_response
+          kv_pairs = {
+            host: host, port: port, mthd: mthd, path: path, post: post, qs: qs,
+            auth: authorization, # authorization is implemented by subclasses
+          }.compact
+          [gs2_header, *kv_pairs.map {|kv| kv.join("=") }, "\1"].join("\1")
+        end
+
         # Returns initial_client_response the first time, then "<tt>^A</tt>".
         def process(data)
           @last_server_response = data
@@ -87,16 +97,6 @@ def process(data)
         # does *not* indicate success.
         def done?; @done end
 
-        # The {RFC7628 §3.1}[https://www.rfc-editor.org/rfc/rfc7628#section-3.1]
-        # formatted response.
-        def initial_client_response
-          kv_pairs = {
-            host: host, port: port, mthd: mthd, path: path, post: post, qs: qs,
-            auth: authorization, # authorization is implemented by subclasses
-          }.compact
-          [gs2_header, *kv_pairs.map {|kv| kv.join("=") }, "\1"].join("\1")
-        end
-
         # Value of the HTTP Authorization header
         #
         # <b>Implemented by subclasses.</b>
@@ -116,6 +116,9 @@ def authorization; raise "must be implemented by subclass" end
       # the bearer token.
       class OAuthBearerAuthenticator < OAuthAuthenticator
 
+        # An OAuth2 bearer token, generally the access token.
+        attr_reader :oauth2_token
+
         # :call-seq:
         #   new(oauth2_token,  **options) -> authenticator
         #   new(oauth2_token:, **options) -> authenticator
@@ -145,9 +148,6 @@ def initialize(oauth2_token_arg = nil, oauth2_token: nil, **args, &blk)
             raise ArgumentError, "missing oauth2_token"
         end
 
-        # An OAuth2 bearer token, generally the access token.
-        attr_reader :oauth2_token
-
         # :call-seq:
         #   initial_response? -> true
         #

lib/net/imap/sasl/plain_authenticator.rb

@@ -10,17 +10,8 @@
 # greater be used for all traffic, and deprecate cleartext access ASAP.  +PLAIN+
 # can be secured by TLS encryption.
 class Net::IMAP::SASL::PlainAuthenticator
-
-  def initial_response?; true end
-
-  def process(data)
-    return "#@authzid\0#@username\0#@password"
-  end
-
-  # :nodoc:
   NULL = -"\0".b
-
-  private
+  private_constant :NULL
 
   # +username+ is the authentication identity, the identity whose +password+ is
   # used.  +username+ is referred to as +authcid+ by
@@ -39,4 +30,10 @@ def initialize(username, password, authzid: nil)
     @authzid  = authzid
   end
 
+  def initial_response?; true end
+
+  def process(data)
+    return "#@authzid\0#@username\0#@password"
+  end
+
 end

lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -2,6 +2,11 @@
 
 class Net::IMAP::SASL::XOAuth2Authenticator
 
+  def initialize(user, oauth2_token)
+    @user = user
+    @oauth2_token = oauth2_token
+  end
+
   def initial_response?; true end
 
   def process(_data)
@@ -10,11 +15,6 @@ def process(_data)
 
   private
 
-  def initialize(user, oauth2_token)
-    @user = user
-    @oauth2_token = oauth2_token
-  end
-
   def build_oauth2_string(user, oauth2_token)
     format("user=%s\1auth=Bearer %s\1\1", user, oauth2_token)
   end