Support keyword parameters for authenticators #71
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
nevans
force-pushed
the
sasl/support-keyword-parameters
branch
2 times, most recently
from
0d8db36
to
c7d7243
Compare
This was referenced Oct 14, 2023
nevans
force-pushed
the
sasl/support-keyword-parameters
branch
4 times, most recently
from
34b1f85
to
f7d0851
Compare
nevans
force-pushed
the
sasl/support-keyword-parameters
branch
from
f7d0851
to
4f9e040
Compare
nevans
force-pushed
the
sasl/support-keyword-parameters
branch
2 times, most recently
from
f8e201f
to
a6280b6
Compare
This adds a new `auth` keyword param to `Net::SMTP.start` and `#start` that can be used to pass any arbitrary keyword parameters to `#authenticate`. The pre-existing `username`, `secret`, etc keyword params will retain their existing behavior as positional arguments to `#authenticate`.
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.
Username can be set by args[0], authcid, username, or user. Secret can be set by args[1], secret, or password. Since all of the existing authenticators have the same API, it is sufficient to update `check_args` in the base class.
This API is a little bit confusing, IMO. But it does preserve backward compatibility, while allowing authenticators that don't allow positional parameters to work without crashing. But, authenticators that require only one parameter—or more than three—will still be inaccessible.
This is convenient for `smtp.start auth: {type:, **etc}`.
nevans
force-pushed
the
sasl/support-keyword-parameters
branch
from
a6280b6
to
a47a7c3
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
authzidfor many mechanisms,warn_deprecationsfor deprecated mechanisms,min_iterationsforSCRAM-*, anonymous_message forANONYMOUS, and so on. Also, although it is convenient to useusernameas an (ambiguous) alias forauthcidorauthzid, andsecretas an (ambiguous) alias forpasswordoroauth2_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):
#authenticatechanges:authenticatekeyword arguments #74)typecan be sent as a keyword parameterNet::SMTP.startand#startchangesauthparameter: a hash of keyword arguments for#authenticate. For backward compatibility, the existingusername,secret, etc are still sent as positional arguments. (Forwardauthenticatekeyword arguments #74)userandsecretpositional arguments optional, as keyword args can be used instead.As currently written, this PR depends on the following other PRs:
Wrap#authenticatewithcritical#65authenticatekeyword arguments #74usernamekeyword param tostartmethods #72auth_method#67