feat(server): Add local evaluation

[dustinbyrne]

💡 Motivation and Context

This PR adds local evaluation capabilities to feature flags. See the updated USAGE.md for details on how to use it.

If you're reviewing this PR, skimming FlagEvaluator.kt, LocalEvaluationPoller.kt, and changes to PostHogFeatureFlags.kt would be the best places to start.

This change is pretty massive. I'm sure there's still a couple of bugs lurking, but test coverage is pretty good. This PR doesn't really change the public API, so we can always follow up with smaller bug fixes.

Resolves #307

💚 How did you test it?

Lots of unit testing and updating the Java sample app to use local eval

📝 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.

[marandaneto]

I'd always use Throwable since it catches more than just Exception

[dustinbyrne]

I typically try to avoid catching Throwable because it includes JVM exceptions that are generally unrecoverable like out of memory, thread death, JVM errors, etc.

[marandaneto]

you do catch a Throwable when executing scheduleAtFixedRate tho.
I usually prefer it because it's a lower level that captures many more errors, but of course, it depends on the throw signature of the methods you call.
I usually prefer to swallow SDK exceptions rather than let them bubble up, and if the caller does not handle the exception. It crashes the app
Sometimes you can get an OOM exception and its not even because the SDK is using a lot of memory, but it used the last bit, but people would still complain its the SDK doing the wrong thing :(
I will let you decide on this since its more server side and might be less of an issue

[marandaneto]

huge PR pheww... :D
i left a few comments, but i'd love to get eyes from the flags team as well, i just checked kotlin-ish code and if stuff made sense but i dont know the logic behind local eval

[dustinbyrne]

Here's the current code coverage summary as of now

Metric	Coverage	Covered/Total
Class	100%	29/29
Method	90.1%	173/192
Branch	69.4%	369/532
Line	87.7%	1051/1198
Instruction	84.6%	4406/5209

[dmarticus]

Generally good, I approve from my end with a few recommendations (see the comments for the specific changes). I also have a few general questions:

• When definitions are reloaded, the feature flag result cache isn't cleared. Is this intentional? Users might get stale results from the cache even after new definitions load.

• If the initial load fails, what happens? The poller will retry, but should there be a fallback to remote evaluation immediately?

• Should there be validation that personalApiKey is provided when localEvaluation=true?

[dmarticus]

This returns without notifying waiters afaict, which means that if it's interrupted, it'll return without setting isLoading = false, so other threads might wait.

Maybe do something like this?

synchronized(loadLock) {
    while (isLoading) {
        try {
            loadLock.wait()
        } catch (e: InterruptedException) {
            Thread.currentThread().interrupt()
            isLoading = false
            loadLock.notifyAll()
            throw InterruptedException("Interrupted while waiting")
        }
    }
}

[dustinbyrne]

The fact that a waiting thread doesn't wake the other threads is by design. If they've got into this block, it's because another thread is executing the try block below. It'll reach a finally block to reset isLoading = false and to wake the waiting threads.

tl;dr - only the loading thread is responsible for waking the waiting threads