feat: Add a start wait timeout for initialization

[kinyoklion]

Adds a start_wait parameter to LaunchDarklyProvider, defaulting to the LaunchDarkly SDK's five seconds.

Closes #55.

• The value is passed to LDClient(config, start_wait) and bounds the whole of initialization once: with a positive value initialize reports the outcome the constructor already waited for rather than waiting again, so a five second start wait cannot become a ten second wait for set_provider_and_wait.
• Initialization fails when the client did not become ready in time; the provider keeps reporting status afterward, so a later connection still makes it ready.
• Zero does not block the constructor at all, and initialize then waits without a deadline for the data source to become valid or to fail permanently.
• Flips the README feature matrix's Initialization row to supported, since this is the change that makes it true.

Implementation details

# With a start wait the client constructor has already waited, so the outcome is whatever it is now.
if self.__start_wait <= 0:
    ready_event.wait()

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

#55, and the matching Java change in openfeature-java-server#61. Related spec change: sdk-specs#257.

Describe the solution you've provided

main has since merged #56, #57 and #58; those are merged into this branch, so start_wait composes with the wrapper information now passed to LDClient, and a failed initialization raises ProviderNotReadyError rather than a fatal error.

Describe alternatives you've considered

Waiting on the ready event for start_wait seconds inside initialize as well: that doubled the effective wait, since the client constructor had already waited the same amount.

Additional context

Testing: make test (84 passed) and make lint. Tests cover the default matching the SDK default and initialization failing without waiting a second time; the timing assertion fails rather than hanging CI if the double wait comes back.

Link to Devin session: https://app.devin.ai/sessions/38a6eaf69fcf41109e136a1d0fe5e899
Open in Devin Desktop: https://app.devin.ai/desktop/session/38a6eaf69fcf41109e136a1d0fe5e899?variant=devin
Requested by: @kinyoklion

---

Note

Overview
Adds an optional start_wait argument to LaunchDarklyProvider (default 5 seconds, aligned with LDClient) so initialization can be bounded instead of waiting indefinitely.

Positive start_wait: the constructor blocks up to that limit while the client connects; initialize does not wait again on the ready event, so total wait time is not doubled (e.g. for set_provider_and_wait). If the client is not ready in time, initialize raises ProviderNotReadyError.

start_wait of 0: the constructor does not block; initialize waits without a deadline until the data source becomes valid or fails permanently (previous behavior).

README marks Initialization as fully supported and documents start_wait. Tests cover the default passed to LDClient and that a positive start_wait does not add a second long wait in initialize (via NeverReadyDataSource).

^{Reviewed by Cursor Bugbot for commit 69390f7. 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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 69390f7. Configure here.}

[cursor]

Timeout drops later ready events

Medium Severity

When start_wait expires, initialize raises ProviderNotReadyError before attaching the data-source and flag listeners. A later LaunchDarkly connection never emits PROVIDER_READY, so OpenFeature stays in ERROR and configuration-change events are also dropped.

 

^{Reviewed by Cursor Bugbot for commit 69390f7. Configure here.}

[devin-ai-integration]

This is correct, and it contradicts a bullet in the description above (now fixed): the raise happens before the status and flag-change listeners are attached, so a provider whose start wait lapses stays silent — no PROVIDER_READY when the connection later succeeds, and no configuration-changed events either. It isn't new to this PR (the same was true of the pre-existing is_initialized() failure path), but a start wait makes it reachable from mere slowness rather than only from a permanent failure.

Not changing it here, since it's the same open question as on openfeature-java-server#61: whether a lapsed start wait is terminal for the provider or just a failed initialization it can recover from. Attaching the listeners before the raise is the fix if it's the latter, and it should be decided the same way in both languages.