♻️ SASL: Add Authenticator base class w/📚docs

* Add many many docs
* Add properties, events, and callbacks
* Add initial_response?
* Add AuthenticationFailure for failures detected by the SASL mechanism.
  This is different from failures detected by the application protocol,
  such as when the IMAP server responds with "NO" or "BAD".

Currently unused, but existing authenticators will be refactored based
on this, and new authenticators will be writte on it.

Author: nevans

lib/net/imap.rb

@@ -984,6 +984,10 @@ def starttls(options = {}, verify = true)
     #
     # ==== Supported SASL Mechanisms
     #
+    #--
+    # n.b. the following table is copied from Net::IMAP::SASL::Authenticator.
+    #++
+    #
     # +PLAIN+::     See PlainAuthenticator.
     #               Login using clear-text username and password.
     #

lib/net/imap/sasl.rb

@@ -32,6 +32,16 @@ module SASL
       autoload :ProhibitedCodepoint, sasl_stringprep_rb
       autoload :BidiStringError,     sasl_stringprep_rb
 
+      # Error raised when the client SASL::Authenticator determines that it
+      # cannot complete successfully during a call to Authenticator#process.
+      #
+      # Note that most \SASL mechanisms cannot detect or report errors until the
+      # protocol-specific outcome message, e.g. a tagged response in \IMAP.
+      # Those authentication errors will be handled or raised by the protocol
+      # client, e.g. a Net::IMAP::NoResponseError.
+      class AuthenticationFailure < Error
+      end
+
       module_function
 
       # See Net::IMAP::StringPrep::SASLprep#saslprep.