fix: allow for providers to safely shutdown

[nicklasl]

Summary

Improves the shutdown behaviour of the ProviderRepository to ensure safe termination of the task executor. The previous implementation called shutdown() on the executor but did not wait for termination, potentially leading to abrupt shutdown, aborted provider shutdown sequences or hanging threads.

Changes

• Added graceful shutdown handling in ProviderRepository.shutdown() with a 3-second timeout
• Added shutdown state tracking to prevent race conditions
• Handles RejectedExecutionException when tasks are submitted to a shut down executor

Implementation Details

The shutdown process now:

1. Calls shutdown() on the task executor to prevent new tasks
2. Waits up to 3 seconds for running tasks to complete via awaitTermination()
3. If tasks don't complete within the timeout, calls shutdownNow() to force termination
4. Properly handles InterruptedException by calling shutdownNow() and restoring the interrupt flag
5. Prevents new providers from being registered during shutdown via AtomicBoolean flag
6. Handles RejectedExecutionException by running provider shutdown synchronously when executor is closed

Test Coverage

Added comprehensive test coverage for shutdown behavior:
[x] Successful shutdown when executor terminates within timeout
[x] Forced shutdown when executor does not terminate within timeout
[x] Graceful handling of interruption during shutdown
[x] Protection against indefinite hangs during shutdown
[x] Concurrent shutdown calls (idempotent behavior)
[x] Shutdown during provider initialization
[x] Provider replacement during shutdown
[x] Prevention of new provider registration after shutdown starts

Related Issues

#1745

This change aligns with the broader effort to improve shutdown behaviour across the SDK, similar to PR #873 which addresses the same issue on Eventing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.64%. Comparing base (fe108bb) to head (efb3475).

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1744      +/-   ##
============================================
+ Coverage     92.51%   93.64%   +1.13%     
- Complexity      642      648       +6     
============================================
  Files            58       58              
  Lines          1536     1559      +23     
  Branches        170      173       +3     
============================================
+ Hits           1421     1460      +39     
+ Misses           70       56      -14     
+ Partials         45       43       -2     

Flag	Coverage Δ
unittests	93.64% <100.00%> (+1.13%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nicklasl]

I added a commit to additionally prevent race conditions during shutdown:

• Added AtomicBoolean isShuttingDown flag to track repository shutdown state
• setProvider() now throws IllegalStateException if called during shutdown
• Handles RejectedExecutionException when shutdown tasks try to submit to closed executor
• Ensures idempotent shutdown (multiple concurrent calls are safe)

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[chrfwow]

The implementation looks nice, but the tests may have some race conditions

[chrfwow]

How long does the Mocked Provider take to shutdown? Are we sure we interrupt during this time?
Maybe this is a case for a VMLens test

[chrfwow]

We cannot be sure that any of these threads execute in parallel. This should be a VMLens test

[nicklasl]

Thanks, I'll look into making them VMLens tests instead, just need to find some time :)

[nicklasl]

@chrfwow I've been working on the shutdown behavior fix for ProviderRepository a bit on the side and ran into a VMLens issue I could use help with.

I wrote a CT test (ProviderRepositoryCT) to verify concurrent shutdown behavior, but VMLens crashes when ThreadPoolExecutor.shutdown() is called inside AllInterleavings:

  NullPointerException: Cannot invoke "TLinkedList.iterator()" because "tasks" is null
    at com.vmlens...ThreadPoolMap.joinAll()
    at java.util.concurrent.ThreadPoolExecutor.shutdown()
    at dev.openfeature.sdk.EventSupport.shutdown()

Claude tells me that VMLens instruments ThreadPoolExecutor and its internal state gets corrupted when shutdown() runs during test execution. The existing VmLensCT avoids this by calling shutdown() in @AfterEach (outside AllInterleavings), but that defeats the purpose of testing concurrent shutdown.

I've commented out the tests for now but I'm wondering if you've encountered this before? Any ideas for testing concurrent shutdown with VMLens, or should we rely on the regular unit tests?

[chrfwow]

I wonder if we have to wrap this with synchronized (registerStateManagerLock) {, otherwise we might lose additions to this.stateManagers

[chrfwow]

@nicklasl I opened an issue for the NPE in VmLens: vmlens/vmlens#58
If it is not too much work, I would keep the old tests that you had before VmLens, and update to the current version as soon as the issue is fixed. Speaking from experience, VmLens bugs are typically fixed quickly.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud