feat: Add a start wait timeout for initialization

[kinyoklion]

initialize blocked on CompletableFuture.get() with no timeout, so a provider whose data source never became valid and never permanently failed would wait forever.

Closes #58.

• Adds Provider(String sdkKey, LDConfig config, Duration startWait), which configures both the SDK's start wait and the provider's initialization timeout
• A zero duration means no provider-applied timeout, per the OFP spec
• On timeout the provider goes to ERROR and initialize throws, distinct from the existing initialization-failure path
• The existing constructors are unchanged in behavior: they leave the caller's LDConfig.startWait untouched and wait indefinitely, so a caller who configured startWait themselves is not overridden
• Parameter naming follows LDConfig.startWait rather than inventing a cross-provider name

Implementation details

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

#58

Describe the solution you've provided

LDClient only exposes one- and two-argument constructors and LDConfig has no start-wait getter, so the three-argument constructor applies the duration through LDConfig.Builder.startWait(...) and keeps its own copy for the timed get. That also means the two-argument constructor cannot discover the caller's configured start wait to reuse it as a provider timeout, which is why it stays indefinite rather than silently adopting a default.

Describe alternatives you've considered

Making the existing constructors default to the SDK's five second start wait would have given every caller a timeout without an API change, but it overrides a startWait the caller set on their own LDConfig — which the README tells them to do — so it was rejected as a silent behavior change.

Additional context

Testing: ./gradlew test checkstyleMain — all tests and checkstyle pass. New lifecycle tests cover a positive start wait timing out against a data source that never becomes ready, a zero start wait not timing out, and the two-argument constructor preserving a configured start wait.

Link to Devin session: https://app.devin.ai/sessions/38a6eaf69fcf41109e136a1d0fe5e899
Requested by: @kinyoklion

---

Note

Overview
Fixes indefinite blocking during initialize when a data source never becomes valid and never permanently fails.

Adds Provider(String, LDConfig, Duration), which sets both the LaunchDarkly SDK startWait and the provider’s wait on the initialization future. A zero duration keeps the prior behavior (no provider timeout). Existing one- and two-argument constructors are documented to wait indefinitely and no longer override a caller’s LDConfig.startWait for provider timeout purposes.

On timeout, the provider moves to ERROR and initialize throws a RuntimeException (“Wait for initialization timed out.”), separate from the existing permanent-failure path. README initialization docs are updated accordingly; lifecycle tests cover positive timeout, zero wait, and two-arg constructor preserving config startWait.

^{Reviewed by Cursor Bugbot for commit b8e23e1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

@cursor review