From 26176ef1038230dd02b2a401f2d23297f38a4658 Mon Sep 17 00:00:00 2001
From: nicholas evans <nicholas.evans@gmail.com>
Date: Wed, 11 Oct 2023 08:46:25 -0400
Subject: [PATCH] Add `username` keyword param to `start`

Although "user" is a reasonable abbreviation, the parameter is more
accurately described as a "username" or an "authentication identity".
They are synonomous here, with "username" winning when both are present.
---
 lib/net/smtp.rb | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/lib/net/smtp.rb b/lib/net/smtp.rb
index 13e1f1f..7454a2b 100644
--- a/lib/net/smtp.rb
+++ b/lib/net/smtp.rb
@@ -459,15 +459,15 @@ def debug_output=(arg)
 
     #
     # :call-seq:
-    #  start(address, port = nil, helo: 'localhost', user: nil, secret: nil, authtype: nil, tls: false, starttls: :auto, tls_verify: true, tls_hostname: nil, ssl_context_params: nil) { |smtp| ... }
-    #  start(address, port = nil, helo = 'localhost', user = nil, secret = nil, authtype = nil) { |smtp| ... }
+    #  start(address, port = nil, helo: 'localhost', username: nil, secret: nil, authtype: nil, tls: false, starttls: :auto, tls_verify: true, tls_hostname: nil, ssl_context_params: nil) { |smtp| ... }
+    #  start(address, port = nil, helo = 'localhost', username = nil, secret = nil, authtype = nil) { |smtp| ... }
     #
     # Creates a new Net::SMTP object and connects to the server.
     #
     # This method is equivalent to:
     #
     #   Net::SMTP.new(address, port, tls_verify: flag, tls_hostname: hostname, ssl_context_params: nil)
-    #     .start(helo: helo_domain, user: account, secret: password, authtype: authtype)
+    #     .start(helo: helo_domain, username: account, secret: password, authtype: authtype)
     #
     # See also: Net::SMTP.new, #start
     #
@@ -514,7 +514,7 @@ def debug_output=(arg)
     #
     # +authtype+ is the SASL authentication mechanism.
     #
-    # +user+ is the authentication or authorization identity.
+    # +username+ or +user+ is the authentication or authorization identity.
     #
     # +secret+ or +password+ is your password or other authentication token.
     #
@@ -538,15 +538,16 @@ def debug_output=(arg)
     #
     def SMTP.start(address, port = nil, *args, helo: nil,
                    user: nil, secret: nil, password: nil, authtype: nil,
+                   username: nil,
                    tls: false, starttls: :auto,
                    tls_verify: true, tls_hostname: nil, ssl_context_params: nil,
                    &block)
       raise ArgumentError, "wrong number of arguments (given #{args.size + 2}, expected 1..6)" if args.size > 4
       helo ||= args[0] || 'localhost'
-      user ||= args[1]
+      username ||= user || args[1]
       secret ||= password || args[2]
       authtype ||= args[3]
-      new(address, port, tls: tls, starttls: starttls, tls_verify: tls_verify, tls_hostname: tls_hostname, ssl_context_params: ssl_context_params).start(helo: helo, user: user, secret: secret, authtype: authtype, &block)
+      new(address, port, tls: tls, starttls: starttls, tls_verify: tls_verify, tls_hostname: tls_hostname, ssl_context_params: ssl_context_params).start(helo: helo, username: username, secret: secret, authtype: authtype, &block)
     end
 
     # +true+ if the \SMTP session has been started.
@@ -556,8 +557,8 @@ def started?
 
     #
     # :call-seq:
-    #  start(helo: 'localhost', user: nil, secret: nil, authtype: nil) { |smtp| ... }
-    #  start(helo = 'localhost', user = nil, secret = nil, authtype = nil) { |smtp| ... }
+    #  start(helo: 'localhost', username: nil, secret: nil, authtype: nil) { |smtp| ... }
+    #  start(helo = 'localhost', username = nil, secret = nil, authtype = nil) { |smtp| ... }
     #
     # Opens a TCP connection and starts the SMTP session.
     #
@@ -571,7 +572,7 @@ def started?
     #
     # +authtype+ is the SASL authentication mechanism.
     #
-    # +user+ is the authentication or authorization identity.
+    # +username+ or +user+ is the authentication or authorization identity.
     #
     # +secret+ or +password+ is your password or other authentication token.
     #
@@ -595,7 +596,7 @@ def started?
     #
     #     require 'net/smtp'
     #     smtp = Net::SMTP.new('smtp.mail.server', 25)
-    #     smtp.start(helo: helo_domain, user: account, secret: password, authtype: authtype) do |smtp|
+    #     smtp.start(helo: helo_domain, username: account, secret: password, authtype: authtype) do |smtp|
     #       smtp.send_message msgstr, 'from@example.com', ['dest@example.com']
     #     end
     #
@@ -619,10 +620,11 @@ def started?
     # * Net::ReadTimeout
     # * IOError
     #
-    def start(*args, helo: nil, user: nil, secret: nil, password: nil, authtype: nil)
+    def start(*args, helo: nil, user: nil, secret: nil, password: nil, authtype: nil,
+              username: nil)
       raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..4)" if args.size > 4
       helo ||= args[0] || 'localhost'
-      user ||= args[1]
+      username ||= user || args[1]
       secret ||= password || args[2]
       authtype ||= args[3]
       if defined?(OpenSSL::VERSION)
@@ -639,13 +641,13 @@ def start(*args, helo: nil, user: nil, secret: nil, password: nil, authtype: nil
       end
       if block_given?
         begin
-          do_start helo, user, secret, authtype
+          do_start helo, username, secret, authtype
           return yield(self)
         ensure
           do_finish
         end
       else
-        do_start helo, user, secret, authtype
+        do_start helo, username, secret, authtype
         return self
       end
     end