net-smtp icon indicating copy to clipboard operation
net-smtp copied to clipboard

Support keyword parameters for authenticators

Open nevans opened this issue 1 year ago • 1 comments

Several SASL mechanisms have zero or one required parameters, so it doesn't make sense to require positional "user" and "secret" parameters. And in some cases, the semantics of the parameters don't align cleanly with the semantics implied by "user" and "secret".

And many SASL mechanisms will need to be able to take extra arguments. For example: authzid for many mechanisms, warn_deprecations for deprecated mechanisms, min_iterations for SCRAM-*, anonymous_message for ANONYMOUS, and so on. Also, although it is convenient to use username as an (ambiguous) alias for authcid or authzid, and secret as an (ambiguous) alias for password or oauth2_token, it is also useful to have keyword parameters that keep stable semantics across many different mechanisms.

So, the API needs to be updated so that 1) positional parameters are not required, 2) keyword parameters are enabled. For semantic clarity, positional parameters should be seen as a convenience, and keyword parameters should be considered the basic form.

This PR does several things (each split into their own commit):

  • #authenticate changes:
    • keyword args are forwarded to the authenticator (#74)
    • positional args are optional
    • type can be sent as a keyword parameter
  • Net::SMTP.start and #start changes
    • Add auth parameter: a hash of keyword arguments for #authenticate. For backward compatibility, the existing username, secret, etc are still sent as positional arguments. (#74)
  • Adds keyword parameters to all existing authenticators. This makes user and secret positional arguments optional, as keyword args can be used instead.

As currently written, this PR depends on the following other PRs:

  • ~#65~
  • #74
  • #72
    • #66
  • #73
    • #67

nevans avatar Oct 14 '23 17:10 nevans

@tmtm Thanks for taking the time to review all of my PRs! I've extracted #74 from this PR, because those are the most important and (I hope) least controversial changes. However, the tests for #74 are still in this PR. Let me know if you want anything changed in either PR. Thanks again!

nevans avatar Nov 07 '23 23:11 nevans