feat: adds forceRefreshOnFailure flag, for refreshing token on error

[skeggse]

It's highly unlikely, but the expiry_date could be wrong, or the comparison in isTokenExpiring could fail due to an inaccurate system clock. As a further fallback behavior, some developers may wish to opt-in to attempting a refresh if Google's servers respond with a status code that may indicate the token has expired.

• Tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[googlebot]

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

[bcoe]

👋 @skeggse thanks for the contribution 👍 I have it on my plate this week to dig into why the heck refresh token logic sometimes fails, I'll get back to reviewing this once I've done a bit of a deep dive on the functionality.

[bcoe]

@skeggse I addressed a major issue with our refresh logic here:

#794

Do you think that this functionality is still something folks might need? If so I might just call the feature alwaysRefresh, and we could use it to set forceReferesh to true when getting a token?

[skeggse]

I think this is still useful, and would like to see a solution similar to this one that doesn't depend on local state (like the system clock). I'd also like to avoid refreshing unless we get a signal that the token may not be up to date, as our analysis indicates that multiple api clients refreshing the token can result in some of the access tokens being invalid - we've implemented a bunch of extra locking around the token refresh process to work around this.

[bcoe]

@skeggse how would the locking be facilitated in this case, you'd only have one of your clients configured to refresh, and several with no eager refresh or alwaysLazyRefresh?

[skeggse]

@bcoe we extend the OAuth2Client to override the refreshTokenNoCache method and wrap the functionality in a pessimistic lock. Any additional logic to attempt refreshes in other contexts simply folds into that extended functionality.

Funny enough, our solution actually fairly well mirrors the approach proposed by the OP of #41.

[bcoe]

@skeggse, I'm open to this feature, but I don't quite understand the flag lazyRefresh, I might call it something like forceRefreshOnFailure?

[skeggse]

Sounds good to me! The flag just means that we should refresh the token in lazy cases, but your flag is far clearer.

[bcoe]

awesome, I'll work on landing this soon.

[codecov]

Codecov Report

Merging #790 into master will increase coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #790      +/-   ##
==========================================
+ Coverage   84.52%   84.54%   +0.01%     
==========================================
  Files          17       17              
  Lines         950      951       +1     
  Branches      211      211              
==========================================
+ Hits          803      804       +1     
  Misses         87       87              
  Partials       60       60

Impacted Files	Coverage Δ
src/auth/refreshclient.ts	88.57% <ø> (ø)	⬆️
src/auth/jwtclient.ts	88.5% <100%> (ø)	⬆️
src/auth/oauth2client.ts	82.78% <100%> (+0.05%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d0b7f8b...1f6c252. Read the comment docs.

[bcoe]

@skeggse I want to use this later today as an example of how our release process works, it's not actually blocked by anything on your end 👍

[skeggse]

@bcoe awesome, love it!