feat(server): Add local evaluation (#299)

* feat(core): Add `localEvaluation` API

* feat(core): Add an optional shutdown override to Feature Flags

* docs(core): Update CHANGELOG

* feat(server): Add feature flags local evaluation

* docs(server): Update CHANGELOG

* docs(server): Update USAGE

* chore: Update Java sample to include local eval

* Don't shadow reserved keyword identifiers

* Drop a list allocation

* Add enums for property operators and types

* Regex patterns are static

* Separate duties in feature flags

This cleans things up for future `onlyEvaluateLocally` config and
sending feature flags on capture

* refactor: Move local eval models to core

Deserialization is handled here, paired closely with the Api. This
simplifies deserialization in the server SDK.

* refactor: Use deserialization from core

* fix: Flag definitions are loaded synchronously if missing

* fix: Use group properties when evaluating group flags

* test: Use JSON objects

* test: Add flag dependency tests

This brings method coverage to 92% overall, line 85% overall.

* fix: Mark the poller as daemon

It'll automatically clean up in case the developer forgets to call
posthog.close()

* chore(java-sample): Move logic out of onFeatureFlags

It's not necessary considering the first request to trigger local
evaluation will synchronously retrieve flag definitions if they're not
yet loaded.

* docs(core): Update CHANGELOG

* chore(server): apply formatter

* fix: Properly type `userProperties`/`groupProperties`

* feat: Setting `personalApiKey` turns local eval on by default

* fix(server): Skip flags with ensure_experience_continuity

* refactor(server): Inherit `PostHogStateless`

Aggregation makes it difficult to access `featureFlags` without exposing
it

* feat(server): Add `reloadFeatureFlags` method

This reloads feature flag definitions, and is present in other
server-side SDKs

* fix(server): Improve synchronization of flag definitions

Previously the synchronization prevented flag definitions from being
overwritten. This now ensures the poller and the client don't load flag
definitions at the same time.

* fix(server): Catch errors on feature flag init

* style: Fix up a comment

* fixup! style: Fix up a comment

* style: Missing newline

* style: spotlessApply

* chore: apiDump

* test: Use a latch to reduce flakiness in CI

Author: dustinbyrne

posthog-samples/posthog-java-sample/src/main/java/com/posthog/java/sample/PostHogJavaExample.java

@@ -1,26 +1,31 @@
 package com.posthog.java.sample;
 
+import com.posthog.server.PostHog;
 import com.posthog.server.PostHogCaptureOptions;
 import com.posthog.server.PostHogConfig;
-import com.posthog.server.PostHog;
+import com.posthog.server.PostHogFeatureFlagOptions;
 import com.posthog.server.PostHogInterface;
 
 import java.util.HashMap;
-import java.util.Map;
 
 /**
  * Simple Java 1.8 example demonstrating PostHog usage
  */
 public class PostHogJavaExample {
+
     public static void main(String[] args) {
         PostHogConfig config = PostHogConfig
-                .builder("phc_wz4KZkikEluCCdfY2B2h7MXYygNGdTqFgjbU7I1ZdVR")
+                .builder("phc_wxtaSxv9yC8UYxUAxNojluoAf41L8p6SJZmiTMtS8jA")
+                .personalApiKey("phs_DuaFTmUtxQNj5R2W03emB1jMLIX5XwDvrt3DKfi5uYNcxzd")
+                .host("http://localhost:8010")
+                .localEvaluation(true)
+                .debug(true)
                 .build();
 
-        PostHogInterface postHog = PostHog.with(config);
+        PostHogInterface posthog = PostHog.with(config);
 
-        postHog.group("distinct-id", "company", "some-company-id");
-        postHog.capture(
+        posthog.group("distinct-id", "company", "some-company-id");
+        posthog.capture(
                 "distinct-id",
                 "new-purchase",
                 PostHogCaptureOptions
@@ -31,29 +36,40 @@ public static void main(String[] args) {
 
         HashMap<String, Object> userProperties = new HashMap<>();
         userProperties.put("email", "[email protected]");
-        postHog.identify("distinct-id", userProperties);
+        posthog.identify("distinct-id", userProperties);
 
         // AVOID - Anonymous inner class holds reference to outer class.
         // The following won't serialize properly.
-        // postHog.identify("user-123", new HashMap<String, Object>() {{
-        //      put("key", "value");
+        // posthog.identify("user-123", new HashMap<String, Object>() {{
+        // put("key", "value");
         // }});
 
-        postHog.alias("distinct-id", "alias-id");
+        posthog.alias("distinct-id", "alias-id");
 
-
-        if (postHog.isFeatureEnabled("distinct-id", "beta-feature", false)) {
+        // Feature flag examples with local evaluation
+        if (posthog.isFeatureEnabled("distinct-id", "beta-feature", false)) {
             System.out.println("The feature is enabled.");
         }
 
-        Object flagValue = postHog.getFeatureFlag("distinct-id", "multi-variate-flag", "default");
+        Object flagValue = posthog.getFeatureFlag("distinct-id", "multi-variate-flag", "default");
         String flagVariate = flagValue instanceof String ? (String) flagValue : "default";
-        Object flagPayload = postHog.getFeatureFlagPayload("distinct-id", "multi-variate-flag");
+        Object flagPayload = posthog.getFeatureFlagPayload("distinct-id", "multi-variate-flag");
 
         System.out.println("The flag variant was: " + flagVariate);
         System.out.println("Received flag payload: " + flagPayload);
 
-        postHog.flush();
-        postHog.close();
+        Boolean hasFilePreview = posthog.isFeatureEnabled(
+                "distinct-id",
+                "file-previews",
+                PostHogFeatureFlagOptions
+                        .builder()
+                        .defaultValue(false)
+                        .personProperty("email", "[email protected]")
+                        .build());
+
+        System.out.println("File previews enabled: " + hasFilePreview);
+
+        posthog.flush();
+        posthog.close();
     }
-}
+}

posthog-server/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## Next
 
+- feat: Add local evaluation for feature flags ([#299](https://github.com/PostHog/posthog-android/issues/299))
 - fix: Restructured `groupProperties` and `userProperties` types to match the API and other SDKs ([#312](https://github.com/PostHog/posthog-android/pull/312))
 
 ## 1.1.0 - 2025-10-03

posthog-server/USAGE.md

@@ -92,6 +92,9 @@ PostHogConfig config = PostHogConfig.builder("phc_your_api_key_here")
 - `flushIntervalSeconds`: Interval between automatic flushes (default: `30`)
 - `featureFlagCacheSize`: The maximum number of feature flags results to cache (default: `1000`)
 - `featureFlagCacheMaxAgeMs`: The maximum age of a feature flag cache record in memory in milliseconds (default: `300000` or five minutes)
+- `localEvaluation`: Enable local evaluation of feature flags (default: `false`)
+- `personalApiKey`: Personal API key required for local evaluation (default: `null`)
+- `pollIntervalSeconds`: Interval for polling flag definitions for local evaluation (default: `30`)
 
 ## Capturing Events
 
@@ -202,6 +205,58 @@ postHog.identify("user123", userProperties, userPropertiesSetOnce);
 
 ## Feature Flags
 
+### Local Evaluation (Experimental)
+
+Local evaluation allows the SDK to evaluate feature flags locally without making API calls for each flag check. This reduces latency and API costs.
+
+**How it works:**
+
+1. The SDK periodically polls for flag definitions from PostHog (every 30 seconds by default)
+2. Flags are evaluated locally using cached definitions and properties provided by the caller
+3. If evaluation is inconclusive (missing properties, etc.), the SDK falls back to the API
+
+**Requirements:**
+
+- A feature flags secure API key _or_ a personal API key
+  - A feature flags secure API key can be obtained via PostHog → Settings → Project → Feature Flags → Feature Flags Secure API key
+  - A personal API key can be generated via PostHog → Settings → Account → Personal API Keys
+- The `localEvaluation` config option set to `true`
+
+#### Kotlin
+
+```kotlin
+val config = PostHogConfig(
+    apiKey = "phc_your_api_key_here",
+    host = "https://your-posthog-instance.com",
+    localEvaluation = true,
+    personalApiKey = "phx_your_personal_api_key_here",
+    pollIntervalSeconds = 30  // Optional: customize polling interval
+)
+```
+
+#### Java
+
+```java
+PostHogConfig config = PostHogConfig.builder("phc_your_api_key_here")
+    .host("https://your-posthog-instance.com")
+    .localEvaluation(true)
+    .personalApiKey("phx_your_personal_api_key_here")
+    .pollIntervalSeconds(30)  // Optional: customize polling interval
+    .build();
+```
+
+**Benefits:**
+
+- **Reduced latency**: No API call needed for most flag evaluations
+- **Lower costs**: Fewer API requests in most cases
+- **Offline support**: Flags continue to work with cached definitions
+
+**Limitations:**
+
+- Requires person/group properties to be provided with each call
+- Falls back to API for cohort-based flags without local cohort data
+- May not reflect real-time flag changes (respects polling interval)
+
 ### Check if Feature is Enabled
 
 #### Kotlin

posthog-server/api/posthog-server.api

@@ -1,4 +1,4 @@
-public final class com/posthog/server/PostHog : com/posthog/server/PostHogInterface {
+public final class com/posthog/server/PostHog : com/posthog/PostHogStateless, com/posthog/server/PostHogInterface {
 	public static final field Companion Lcom/posthog/server/PostHog$Companion;
 	public fun <init> ()V
 	public fun alias (Ljava/lang/String;Ljava/lang/String;)V
@@ -25,6 +25,7 @@ public final class com/posthog/server/PostHog : com/posthog/server/PostHogInterf
 	public fun isFeatureEnabled (Ljava/lang/String;Ljava/lang/String;Lcom/posthog/server/PostHogFeatureFlagOptions;)Z
 	public fun isFeatureEnabled (Ljava/lang/String;Ljava/lang/String;Z)Z
 	public fun isFeatureEnabled (Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;)Z
+	public fun reloadFeatureFlags ()V
 	public fun setup (Lcom/posthog/server/PostHogConfig;)V
 	public static final fun with (Lcom/posthog/server/PostHogConfig;)Lcom/posthog/server/PostHogInterface;
 }
@@ -86,10 +87,11 @@ public class com/posthog/server/PostHogConfig {
 	public static final field DEFAULT_HOST Ljava/lang/String;
 	public static final field DEFAULT_MAX_BATCH_SIZE I
 	public static final field DEFAULT_MAX_QUEUE_SIZE I
+	public static final field DEFAULT_POLL_INTERVAL_SECONDS I
 	public static final field DEFAULT_US_ASSETS_HOST Ljava/lang/String;
 	public static final field DEFAULT_US_HOST Ljava/lang/String;
-	public fun <init> (Ljava/lang/String;Ljava/lang/String;ZZZZIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;Ljava/net/Proxy;III)V
-	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;ZZZZIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;Ljava/net/Proxy;IIIILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;ZZZZIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;Ljava/net/Proxy;IIIZLjava/lang/String;I)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;ZZZZIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;Ljava/net/Proxy;IIIZLjava/lang/String;IILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V
 	public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V
 	public static final fun builder (Ljava/lang/String;)Lcom/posthog/server/PostHogConfig$Builder;
@@ -102,9 +104,12 @@ public class com/posthog/server/PostHogConfig {
 	public final fun getFlushAt ()I
 	public final fun getFlushIntervalSeconds ()I
 	public final fun getHost ()Ljava/lang/String;
+	public final fun getLocalEvaluation ()Z
 	public final fun getMaxBatchSize ()I
 	public final fun getMaxQueueSize ()I
 	public final fun getOnFeatureFlags ()Lcom/posthog/PostHogOnFeatureFlags;
+	public final fun getPersonalApiKey ()Ljava/lang/String;
+	public final fun getPollIntervalSeconds ()I
 	public final fun getPreloadFeatureFlags ()Z
 	public final fun getProxy ()Ljava/net/Proxy;
 	public final fun getRemoteConfig ()Z
@@ -117,9 +122,12 @@ public class com/posthog/server/PostHogConfig {
 	public final fun setFeatureFlagCalledCacheSize (I)V
 	public final fun setFlushAt (I)V
 	public final fun setFlushIntervalSeconds (I)V
+	public final fun setLocalEvaluation (Z)V
 	public final fun setMaxBatchSize (I)V
 	public final fun setMaxQueueSize (I)V
 	public final fun setOnFeatureFlags (Lcom/posthog/PostHogOnFeatureFlags;)V
+	public final fun setPersonalApiKey (Ljava/lang/String;)V
+	public final fun setPollIntervalSeconds (I)V
 	public final fun setPreloadFeatureFlags (Z)V
 	public final fun setProxy (Ljava/net/Proxy;)V
 	public final fun setRemoteConfig (Z)V
@@ -137,9 +145,12 @@ public final class com/posthog/server/PostHogConfig$Builder {
 	public final fun flushAt (I)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun flushIntervalSeconds (I)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun host (Ljava/lang/String;)Lcom/posthog/server/PostHogConfig$Builder;
+	public final fun localEvaluation (Z)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun maxBatchSize (I)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun maxQueueSize (I)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun onFeatureFlags (Lcom/posthog/PostHogOnFeatureFlags;)Lcom/posthog/server/PostHogConfig$Builder;
+	public final fun personalApiKey (Ljava/lang/String;)Lcom/posthog/server/PostHogConfig$Builder;
+	public final fun pollIntervalSeconds (I)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun preloadFeatureFlags (Z)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun proxy (Ljava/net/Proxy;)Lcom/posthog/server/PostHogConfig$Builder;
 	public final fun remoteConfig (Z)Lcom/posthog/server/PostHogConfig$Builder;
@@ -209,6 +220,7 @@ public abstract interface class com/posthog/server/PostHogInterface {
 	public abstract fun isFeatureEnabled (Ljava/lang/String;Ljava/lang/String;Lcom/posthog/server/PostHogFeatureFlagOptions;)Z
 	public abstract fun isFeatureEnabled (Ljava/lang/String;Ljava/lang/String;Z)Z
 	public abstract fun isFeatureEnabled (Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;)Z
+	public abstract fun reloadFeatureFlags ()V
 	public abstract fun setup (Lcom/posthog/server/PostHogConfig;)V
 }
 

posthog-server/src/main/java/com/posthog/server/PostHog.kt

@@ -1,37 +1,36 @@
 package com.posthog.server
 
+import com.posthog.PostHog
 import com.posthog.PostHogStateless
-import com.posthog.PostHogStatelessInterface
-
-public class PostHog : PostHogInterface {
-    private var instance: PostHogStatelessInterface? = null
+import com.posthog.server.internal.PostHogFeatureFlags
 
+public class PostHog : PostHogStateless(), PostHogInterface {
     override fun <T : PostHogConfig> setup(config: T) {
-        instance = PostHogStateless.with(config.asCoreConfig())
+        super.setup(config.asCoreConfig())
     }
 
     override fun close() {
-        instance?.close()
+        super.close()
     }
 
     override fun identify(
         distinctId: String,
         userProperties: Map<String, Any>?,
         userPropertiesSetOnce: Map<String, Any>?,
     ) {
-        instance?.identify(
+        super<PostHogStateless>.identify(
             distinctId,
             userProperties,
             userPropertiesSetOnce,
         )
     }
 
     override fun flush() {
-        instance?.flush()
+        super.flush()
     }
 
     override fun debug(enable: Boolean) {
-        instance?.debug(enable)
+        super.debug(enable)
     }
 
     override fun capture(
@@ -43,7 +42,7 @@ public class PostHog : PostHogInterface {
         groups: Map<String, String>?,
         timestamp: java.util.Date?,
     ) {
-        instance?.captureStateless(
+        super.captureStateless(
             event,
             distinctId,
             properties,
@@ -62,14 +61,14 @@ public class PostHog : PostHogInterface {
         personProperties: Map<String, Any?>?,
         groupProperties: Map<String, Map<String, Any?>>?,
     ): Boolean {
-        return instance?.isFeatureEnabledStateless(
+        return super.isFeatureEnabledStateless(
             distinctId,
             key,
             defaultValue,
             groups,
             personProperties,
             groupProperties,
-        ) ?: false
+        )
     }
 
     override fun getFeatureFlag(
@@ -80,7 +79,7 @@ public class PostHog : PostHogInterface {
         personProperties: Map<String, Any?>?,
         groupProperties: Map<String, Map<String, Any?>>?,
     ): Any? {
-        return instance?.getFeatureFlagStateless(
+        return super.getFeatureFlagStateless(
             distinctId,
             key,
             defaultValue,
@@ -98,7 +97,7 @@ public class PostHog : PostHogInterface {
         personProperties: Map<String, Any?>?,
         groupProperties: Map<String, Map<String, Any?>>?,
     ): Any? {
-        return instance?.getFeatureFlagPayloadStateless(
+        return super.getFeatureFlagPayloadStateless(
             distinctId,
             key,
             defaultValue,
@@ -114,7 +113,7 @@ public class PostHog : PostHogInterface {
         key: String,
         groupProperties: Map<String, Any>?,
     ) {
-        instance?.groupStateless(
+        super.groupStateless(
             distinctId,
             type,
             key,
@@ -126,12 +125,16 @@ public class PostHog : PostHogInterface {
         distinctId: String,
         alias: String,
     ) {
-        instance?.aliasStateless(
+        super.aliasStateless(
             distinctId,
             alias,
         )
     }
 
+    override fun reloadFeatureFlags() {
+        (featureFlags as? PostHogFeatureFlags)?.loadFeatureFlagDefinitions()
+    }
+
     public companion object {
         /**
          * Set up the SDK and returns an instance that you can hold and pass it around