feat(flags): add feature_flags_async_load option to keep definition fetches off the calling thread

[flivni]

💡 Motivation and Context

PostHog's Server-side Local Evaluation feature improves
performance by evaluating flags in-process, with definitions refreshed by a background polling thread.

The problem is ... definitions are not always requested in a background thread. This could result in unexpected request-latency spikes which on a busy server could cascade into an outage.

Two issues

• get_feature_flag reverts to synchronous behavior when flags have not yet successfully loaded. If, for example, PostHog is down on boot, every call to get_feature_flag will be synchronous until a fetch succeeds; request times might go from ms to seconds. Note: A 402 quota response clears cached definitions and thereby also re-arms inline fetching.

• PostHog::Client performs a blocking, synchronous fetch on initialization. In the common case, the block is perhaps 1-2s. But in the case where PostHog is down or there is network connectivity issue, this can be a 10s timeout. In clustered Puma with preload_app!, this can be paid twice serially (master boot, then on_worker_boot). Additionally, PR fix(flags): Retry flag requests on transient network errors #198 adds a retry, also doubling. Many platforms (e.g. Heroku) have boot time constraints. It's possible that a PostHog outage or network connectivity issue could cause apps that have strict boot timeouts to be unable to (re)start.

A solution

This PR aims to address both these issues by adding an initialization parameter feature_flags_async_load, while, by default, maintaining the current, sometimes synchronous, behavior.

When enabled, definitions are fetched only on the existing poller thread: its first tick fires immediately at boot (run_now: true), and failures retry on the normal polling cadence. No new threads.

Also introduced is a new public API method feature_flags_loaded? which allows users to check if feature flags have been loaded (see code sample below).

Fix: A 402 quota response now clears flag_definitions_loaded_at along with the definitions it discards, so feature_flags_loaded? and evaluate_flags(...).flag_definitions_loaded_at no longer report definitions as loaded after a quota limit unloads them. This is a minor bugfix, but also a subtle observable change to an existing public field.

Fix: flag_definitions_loaded_at was a plain ivar written by the poller thread (previously only when the initial synchronous load failed; with async load, always), so readers on other threads had no visibility guarantee on JRuby/TruffleRuby. It's now a Concurrent::AtomicReference, which also guarantees that when feature_flags_loaded? returns true, the definitions written before it are visible.

When not to prefer the new fully async behavior

The new, fully asynchronous behavior might not always be preferred. One negative is that with the new feature_flags_async_load set to true, requests following quickly after boot might, even in the healthy case, see nil values for get_feature_flag as the definitions have not yet loaded. But, IMHO, the new behavior is, in most cases, the desirable behavior.

Users who prefer the default synchronous boot, but don't want evaluation calls to fetch synchronously when initial load (or subsequent 402 reload) failed, can use:

if client.feature_flags_loaded?
  client.get_feature_flag(...)
end

💚 How did you test it?

• New spec file (feature_flags_async_load_spec.rb, 7 examples): constructor returns immediately and definitions load asynchronously; sync default unchanged when the option is off; evaluate_flags returns nil fast and starts zero additional fetches while the initial load is in flight; recovery happens on the polling cadence after a failed (500) initial load; reload_feature_flags still fetches synchronously; feature_flags_loaded? is false without a secret_key and goes false again when a 402 discards the definitions. Async waits use the suite's existing eventually helper.
• Full suite: 621 examples, 0 failures. rubocop clean. rake public_api:check passes with the snapshot regenerated for the one new public method.
• End-to-end smoke test against a real local HTTP server with controllable latency and failures, driving the library exactly as an app would:

Scenario	Client.new	Evaluation call
Server slow (2s), sync mode	blocks 2.0s	—
Server slow (2s), async mode	0.00s	nil in 0.00s, then variant once loaded
Server down at boot, async mode	0.00s	nil in 0.00s; recovers via next poll tick after server returns
Server down at boot, sync mode (the bug)	blocks 2.0s	nil in 2.0s, inline re-fetch per call

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (Claude Fable 5 assisted)

Design decisions were human, notably relying on the existing poller timer rather than introducing new threads or concurrency primitives. Product code is ~90% human-written with AI review; tests ~90% AI-written, human-led; documentation AI-outlined, human-written, then AI-copyedited.

An AI multi-agent code review of the branch produced findings that were human-adjudicated: some were fixed here (a cross-thread visibility fix, spec cleanup), several were determined to be pre-existing issues and queued as follow-up PRs, and the rest rejected with rationale.

The human understands all the code in this PR.