Each token is stored along with a 64bit bloom filter that is created
from the set of scopes associated with that token. When retrieving
tokens for a set of scopes a new bloom filter is calculated for the
requested scopes and compared to the filters of all previously fetched
scopes. The bloom filter allows for efficiently skipping entries that
are definitely not a superset.
Seahash is a stable hash, but there isn't any value in serializing it's
value. Instead calculate the value of the hash when deserializing and
only serialize the scopes and tokens. This provides flexibility to
change the hash value in the future without breaking the on-disk format.
Use a BTreeMap to key the tokens by the hash value. On retrieval first
look for a matching hash value and return it if it exists. Only if it
does not exist does it fallback to the subset matching. This makes the
common case where an application uses a consistent set of scopes more
efficient without detrimentally impacting the less common cases.
DefaultHasher is not documented as being consistent. It's best to not
trust that the resulting hash value is consistent even across different
executions of the same binary and even more so across different
versions.
This is already the case when writing a token file. Presumably the only
reason it was an Option was for backwards compatibility, but we're
already breaking compatibility with the change to the hash value so this
seems like an appropriate time to make the change.
This change also highlights how unused the hash value has been
previously. Future changes plan to use the hash value for more efficient
handling.
No caller ever provided a None value. Presumably a None value should
delete the token, but it didn't do that and that would be more clearly
done with a remove or delete method.
These previously accepted a hash and scopes. The hash was required to be
a hash of the provided scopes but that wasn't enforced by the compiler.
We now have the compiler enforce that by creating a HashedScopes type
that ties the scopes and the hash together and pass that into the
storage methods.
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.
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.
Avoid reading and parsing the private key file on every invocation of
token() in favor or reading it once when the ServiceAccountAccess is
built. Also avoid unnecessary allocations when signing JWT tokens and
renamed sub to subject to avoid any confusion with the std::ops::Sub
trait.
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.
This requires enforcing that errors returned from TokenStorage
implementations are Send, which the ones in this crate are, but is a
breaking change because any external implementations may be returning
errors that are !Sync currently.
The motivation for this change is that Box<dyn Error + Send> is not as fully
supported within the rust stdlib as Box<dyn Error + Send + Sync>. In
particular there exists these two From impls:
impl<'a, E: Error + 'a> From<E> for Box<dyn Error + 'a>
impl<'a, E: Error + Send + Sync + 'a> From<E> for Box<dyn Error + Send + Sync + 'a>
but no corresponding impl for
impl<'a, E: Error + Send + 'a> From<E> for Box<dyn Error + Send + 'a>
This may just be an oversight in the rust stdlib that could be fixed,
but in practice it means that dealing with 'Error + Send' types is not
the most ergonomic because the '?' operator can't be used to convert
from a Box<dyn Error + Send> to a Box<dyn Error>.
Since the current implementations (not counting any external ones that
may exist) implement Sync this seems like a good tradeoff to make it a
little easier to use in an ergonomic way.
