This adjusts the code and documentation for `--all-features` and
`--no-default-features` to work correctly. With `--no-default-features`
no `DefaultAuthenticator` is made available. Users are in control of
picking the `Connector` they want to use, and are not forced to stomach
a dependency on `rustls` or `hyper-tls` if their TLS implementation of
choice doesn't happen to match one of the two.
To indicate this, the unstable `doc_cfg` feature is used to build
documentation on docs.rs. That way the generated documentation has
notices on these types that look as such:
> This is supported on crate features hyper-rustls or hyper-tls only.
Additionally this functionality is tested via additional coverage in the
Actions' CI.
Could be helpful when troubleshooting issues with various providers if
the user is able to turn on debug logging. The most critical logging
provided is the request and responses sent and received from the oauth
servers.
What was previously called Token is now TokenInfo and is merely an
internal implementation detail. The publicly visible type is now called
AccessToken and differs from TokenInfo by not including the refresh
token. This makes it a smaller type for users to pass around as well as
reducing the ways that a refresh token may be leaked. Since the
Authenticator is responsible for refreshing the tokens there isn't any
reason users should need to concern themselves with refresh tokens.
Remove expires_in in favor of only having an expires_at DateTime field.
Add a from_json method that deserializes from json data into the
appropriate Token (or Error) and use that consistently throughout the
codebase.
This Removes RefreshError and PollError. Both those types can be fully
represented within Error and there seems little value in distinguishing
that they were resulting from device polling or refreshes. In either
case the user will need to handle the response from token() calls
similarly. This also removes the AuthenticatorDelegate since it only
served to notify users when refreshes failed, which can already be done
by looking at the return code from token. DeviceFlow no longer has the
ability to set a wait_timeout. This is trivial to do by wrapping the
token() call in a tokio::Timeout future so there's little benefit for
users specifying this value. The DeviceFlowDelegate also no longer has
the ability to specify when to abort, or alter the interval polling
happens on, but it does gain understanding of the 'slow_down' response
as documented in the oauth rfc. It seemed very unlikely the delegate was
going to do anything other that timeout after a given time and that's
already possible using tokio::Timeout so it needlessly complicated the
implementation.
Based on the comment in the code the justification for the change was
because old FlowDelegates used to contain newlines and changing how the
returned string from the delegate was handled would be a breaking
change. In this case it should be safe to remove the hack because we're
breaking compatibility. All users that once implemented FlowDelegate
will now need to implement InstalledFlowDelegate and uphold the new
contract which implicitly means the authcode returned should represent
the authcode and nothing more. No manipulation of the returned string
will be done.
Prior to this change the only place present_user_url is called overwrote
the error with a static string. After this change the error returned is
appended to the message. No need to make the signature more complicated
when the error is always going to be flattened to a string anyway.
Each flow invokes a non-overlapping set of methods. There doesn't appear
to be any benefit in having both flows use a common trait. The benefit
of splitting the traits is that it makes it clear which methods need to
be updated for each flow type where previously comments were required to
communicate that information.
Prior to this change DeviceFlow and InstalledFlow were used within
Authenticator, while ServiceAccountAccess was used on it's own. AFAICT
this was the case because ServiceAccountAccess never used refresh tokens
and Authenticator assumed all tokens contained refresh tokens.
Authenticator was recently modified to handle the case where a token
does not contain a refresh token so I don't see any reason to keep the
service account access separate anymore. Folding it into the
authenticator provides a nice consistent interface, and the service
account implementation no longer needs to provide it's own caching since
it is now handled by Authenticator.
No more need to macro_use serde. Order the imports consistently (albeit
somewhat arbitrary), starting with items from this crate, followed by
std, followed by external crates.
RequestError is the error value that encompasses all errors from the
authenticators. Their is an established convention of using Error as the
name for those types.
Restructure the modules and imports to increase the signal to noise
ration on the cargo doc landing page. This includes exposing some
modules as public so that they can contain things that need to be public
but that users will rarely need to interact with. Most items from
types.rs were moved into an error.rs module that is now exposed
publicly.
1) Remove the GetToken trait. The trait seemed to be organically
designed. It appeared to be mostly tailored for simplifying the
implementation since there was no way for users to provide their own
implementation to Authenticator. It sadly seemed to get in the way of
implementations more than it helped. An enum representing the known
implementations is a more straightforward way to accomplish the goal and
also has the benefit of not requiring Boxing when returning features
(which admittedly is a minor concern for this use case).
2) Reduce the number of type parameters by using trait object for
delegates. This simplifies the code considerably and the performance
impact of virtual dispatch for the delegate calls is a non-factor.
3) With the above two simplifications it became easier to unify the
public interface for building an authenticator. See the examples for how
InstalledFlow, DeviceFlow, and ServiceAccount authenticators are now created.
Currently the authenticator will panic when trying to refresh an expired
token that does not have a refresh token. This change handles it so that
the authenticator will only attempt a refresh when a refresh_token
exists, and otherwise will attempt to retrieve a fresh token.
In favor of making it the default and removing the option to specify a
port to listen on. If needed a variant can be added to specify a port
explicitly, but most users should want an ephemeral port chosen so
making it the default makes sense while other breaking changes are in
flight.
JsonErrorOr is an untagged enum that is generic over arbitrary data.
This means that when deserializing JsonErrorOr<T> it will first check
the json field for an 'error' attribute. If one exists it will
deserialize into the JsonErrorOr::Err variant that contains a JsonError.
If the message doesn't contain an 'error' field it will attempt to
deserialize T into he JsonErrorOr::Data variant.
Along with the public facing change the implementation has been modified
to no longer clone the scopes instead using the pointer to the scopes
the user provided. This greatly reduces the number of allocations on
each token() call.
Note that this also changes the hashing method used for token storage in
an incompatible way with the previous implementation. The previous
implementation pre-sorted the vector and hashed the contents to make the
result independent of the ordering of the scopes. Instead we now combine
the hash values of each scope together with XOR, thus producing a hash
value that does not depend on order without needing to allocate another
vector and sort.
Beyond simply moving to the builder pattern for intialization this has a
few other effects.
The DeviceFlow and InstalledFlow can no longer be used without an
associated Authenticator. This is becaus they no longer have any
publicly accessible constructor. All initialization goes through the
Authenticator. This also means that the flows are always initialized
with a clone of the hyper client used by the Authenticator.
The authenticator uses the builder pattern which allows omitting
optional fields. This means that if users simply want a default hyper
client, they don't need to create one explicitly. One will be created
automatically. If users want to specify a hyper client (maybe to allow
sharing a single client between different libraries) they can still do so
by using the hyper_client method on the builder. Additionally for both
AuthenticatorDelegate's and FlowDelegate's if the user does not specify
an override the default ones will be used.
The builders are now exposed publicly with the names of Authenicator,
InstalledFlow, and DeviceFlow. The structs that actually implement those
behaviors are now hidden and only expose the GetToken trait. This means
some methods that were previously publicly accessible are no longer
available, but the methods appeared to be implementation details that
probably shouldn't have been exposed anyway.
Specifying a port of zero has the server listen on an ephemeral port.
Many users may not be aware of that unless they have a background in
networking where that's common practice. I'm also not able to think of
any use cases where listening on a hardcoded port would be beneficial,
so with this change I've opted to remove the ability entirely rather
than simply documenting that almost everybody should specify zero.
Change it to accept an iterator of items that can be converted to
`String`s rather than an iterator of items that can be referenced as
`&str`s.
Primarily this allows it to be called with a larger variety of inputs.
For example ::std::env::args().skip(1) can now be passed directly to
token, where before it would first need to be collected into a vector.
Since all implementations unconditionally collected the iterator into a
vector this shouldn't have any negative impact on performance and should
actually reduce the number of allocations in some uses.
It simplifies the signature since the lifetime bounds are no longer
required.
