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.
The current code uses standard blocking i/o operations (std::fs::*) this
is problematic as it would block the entire futures executor waiting for
i/o.
This change is a major refactoring to make the token storage mechansim
async i/o friendly. The first major decision was to abandon the GetToken
trait. The trait is only implemented internally and there was no
mechanism for users to provide their own, but async fn's are not
currently supported in trait impls so keeping the trait would have
required Boxing futures. This probably would have been fine, but seemed
unnecessary. Instead of a trait the storage mechanism is just an enum
with a choice between Memory and Disk storage.
The DiskStorage works primarily as it did before, rewriting the entire
contents of the file on every set() invocation. The only difference is
that we now defer the actual writing to a separate task so that it does
not block the return of the Token to the user. If disk i/o is too slow
to keep up with the rate of incoming writes it will push back and
will eventually block the return of tokens, this is to prevent a buildup
of in-flight requests. One major drawback to this approach is that any
errors that happen on write are simply logged and no delegate function
is invoked on error because the delegate no longer has the ability to
say to sleep, retry, etc.
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.
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.
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.
This upgrade Hyper to v0.12 and updats to code to work for it. It has
being done with the minimum code change and so the logic is still
aukward for the futures model. This should be addressed in later commits
but I did not want to compilcate an already large commit.
Use the power of the `AsRef` trait to take generic parameters for
several API functions. This makes the API more ergonomic because the
callers may pass in static `str` slices or references to owned `String`s
or even more exotic things like a `Cow`, all based on their particular
situation.
Update the tests and examples to use the most natural types they have
available.
Fixes#77. No existing code should break, as `&String` implements
`AsRef<str>` and `AsRef<Path>`
This is a breaking change; it's supposed to fix#1. Also, it's a
proposal -- not sure if the benefits outweigh the cost of this.
The example/auth.rs binary is not broken by this, as it doesn't use the
API that changed. The tests have been updated accordingly.
I mainly resolved some circular dependencies that had crept in, and
moved code around. I renamed helper.rs because that was not really an
appropriate name anymore, and moved the delegate code into a new module.
