net-smtp
net-smtp copied to clipboard
Support keyword parameters for authenticators
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 existingusername
,secret
, etc are still sent as positional arguments. (#74)
- Add
- Adds keyword parameters to all existing authenticators. This makes
user
andsecret
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
@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!