[GH-288] Add Support for WithSynchronousRefresh Option in CachingProvider for Blocking/Non-Blocking Key Refresh

[developerkunal]

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

🔧 Changes

Added support for blocking and non-blocking key refresh in CachingProvider by introducing the WithSynchronousRefresh option.

• Added WithSynchronousRefresh option to allow developers to choose between blocking and non-blocking key refresh.
• Updated CachingProvider to respect the selected refresh mode.
• Ensured backward compatibility by defaulting to non-blocking refresh.

📚 References

• [Race condition in JWK Caching Provider implementation? #288]

🔬 Testing

• Added unit tests to verify both blocking and non-blocking behavior.
• Validated that the change does not impact existing non-blocking behavior unless explicitly enabled.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.66%. Comparing base (f0aafb9) to head (ac36e8c).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #314      +/-   ##
==========================================
+ Coverage   96.39%   96.66%   +0.26%     
==========================================
  Files           8        8              
  Lines         361      390      +29     
==========================================
+ Hits          348      377      +29     
  Misses         10       10              
  Partials        3        3              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[JohnRoesler]

Hi folks, first off, thank you for your work on this library!

The change made to the NewCachingProvider's opts parameter from ProviderOption to interface{} is a breaking change that unexpectedly caught me when dependabot bumped the minor version of this library.

The fix isn't a big deal, but it's never ideal to introduce a breaking change when the sematic versioning isn't major version.

Also, nothing I saw in the release notes suggested there was a change that needed to be made when switching versions.

@duedares-rvj @developerkunal

[developerkunal]

Hi @JohnRoesler,

Sorry to hear that!

I’ll take a closer look — it’s possible I may have overlooked something during testing. I tested with the existing test cases for options, but if you could share a code snippet of how you're using it, that would really help ensure this doesn’t happen again.

I'll also review how I released the change, in case it unintentionally introduced a breaking change.

Thanks for flagging it!

[JohnRoesler]

hey @developerkunal thanks for the response. Here is what I had:

And here is what i changed it to:

	optsInterface := make([]interface{}, len(opts))

	for i := range opts {
		optsInterface[i] = opts[i]
	}

	provider := jwks.NewCachingProvider(issuerURL, 5*time.Minute, optsInterface...)

[developerkunal]

Hi @JohnRoesler,

Thank you! I took a look and realized I missed this scenario in the release. It looks like we introduced a breaking change without announcing it — I’ll make sure to address it and include a proper announcement in the upcoming releases.

[JohnRoesler]

@developerkunal I know it's hard, since it's such a small change, but it is breaking and any breaking change should come with a major version bump 😬

[developerkunal]

@JohnRoesler Totally agree — I’ll make sure to test things more thoroughly next time.
Thanks again for pointing it out!