feat: intelligent enum for rule pre-compilation (#1791)

Signed-off-by: Todd Baert <todd.baert@dynatrace.com>

Author: toddbaert

providers/flagd/README.md

@@ -160,20 +160,27 @@ Given below are the supported configurations:
 | streamDeadlineMs      | FLAGD_STREAM_DEADLINE_MS                                               | int                      | 600000                        | rpc & in-process                                                                |
 | keepAliveTime         | FLAGD_KEEP_ALIVE_TIME_MS                                               | long                     | 0                             | rpc & in-process                                                                |
 | selector              | FLAGD_SOURCE_SELECTOR                                                  | String                   | null                          | in-process (see [migration guidance](#selector-filtering-in-process-mode-only)) |
-| providerId            | FLAGD_SOURCE_PROVIDER_ID                                               | String                   | null                          | in-process                                                                      |
+| providerId            | FLAGD_PROVIDER_ID (FLAGD_SOURCE_PROVIDER_ID deprecated)                | String                   | null                          | in-process                                                                      |
 | cache                 | FLAGD_CACHE                                                            | String - lru, disabled   | lru                           | rpc                                                                             |
 | maxCacheSize          | FLAGD_MAX_CACHE_SIZE                                                   | int                      | 1000                          | rpc                                                                             |
-| maxEventStreamRetries | FLAGD_MAX_EVENT_STREAM_RETRIES                                         | int                      | 5                             | rpc                                                                             |
-| retryBackoffMs        | FLAGD_RETRY_BACKOFF_MS                                                 | int                      | 1000                          | rpc                                                                             |
+| retryBackoffMs        | FLAGD_RETRY_BACKOFF_MS                                                 | int                      | 1000                          | rpc & in-process                                                                |
+| retryBackoffMaxMs     | FLAGD_RETRY_BACKOFF_MAX_MS                                             | int                      | 12000                         | rpc & in-process                                                                |
+| retryGracePeriod      | FLAGD_RETRY_GRACE_PERIOD                                               | int                      | 5                             | rpc & in-process & file                                                         |
+| fatalStatusCodes      | FLAGD_FATAL_STATUS_CODES                                               | list                     | []                            | rpc & in-process                                                                |
 | offlineFlagSourcePath | FLAGD_OFFLINE_FLAG_SOURCE_PATH                                         | String                   | null                          | file                                                                            |
 | offlinePollIntervalMs | FLAGD_OFFLINE_POLL_MS                                                  | int                      | 5000                          | file                                                                            |
+| contextEnricher       | -                                                                      | function                 | identity                      | in-process                                                                      |
+| compileTargeting      | FLAGD_COMPILE_TARGETING                                                | String - enabled, disabled, auto | auto                    | in-process (experimental)                                                       |
+| reinitializeOnError   | FLAGD_REINITIALIZE_ON_ERROR                                            | boolean                  | false                         | rpc & in-process (experimental)                                                 |
 
 > [!NOTE]  
 > Some configurations are only applicable for RPC resolver.
 
 > [!NOTE]
 > The `selector` option automatically uses the `flagd-selector` header (the preferred approach per [flagd issue #1814](https://github.com/open-feature/flagd/issues/1814)) while maintaining backward compatibility with older flagd versions. See [Selector filtering](#selector-filtering-in-process-mode-only) for details.
->
+
+> [!TIP]
+> The `compileTargeting` option (experimental) controls pre-compilation of JsonLogic targeting rules into Java bytecode for improved evaluation performance. This requires the `jdk.compiler` module at runtime, which is typically not available in JRE-only images (distroless, Alpine, UBI Micro, etc.). In `auto` mode (the default), the provider calls `javax.tools.ToolProvider.getSystemJavaCompiler()` at initialization; if it returns non-null, compilation is enabled, otherwise the interpreter is used. Set to `enabled` to force compilation (a warning is logged if the compiler is unavailable), or `disabled` to always use the interpreter. Note that compilation adds latency to the first evaluation of each rule (source generation, in-memory javac, and class loading); subsequent evaluations of the same rule are faster.
 
 ### Unix socket support
 

providers/flagd/pom.xml

@@ -239,10 +239,6 @@
                                         <include>**/*CTest.java</include>
                                     </includes>
                                     <failIfNoTests>true</failIfNoTests>
-                                    <environmentVariables>
-                                        <!-- disable JsonLogic compilation to reduce VMLens interleaving combinations -->
-                                        <FLAGD_DISABLE_TARGETING_COMPILATION>true</FLAGD_DISABLE_TARGETING_COMPILATION>
-                                    </environmentVariables>
                                 </configuration>
                             </execution>
                         </executions>

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/CompileTargetingMode.java

@@ -0,0 +1,29 @@
+package dev.openfeature.contrib.providers.flagd;
+
+/**
+ * !EXPERIMENTAL!
+ * Controls whether JsonLogic targeting rules are compiled into Java bytecode for improved
+ * evaluation performance. Compilation requires the {@code jdk.compiler} module at runtime,
+ * which is typically not available in JRE-only images.
+ * Compilation adds latency to the first evaluation of each rule (source generation, in-memory
+ * javac, class loading); subsequent evaluations are faster. This trade-off favors long-running
+ * services where rules are evaluated many times.
+ */
+public enum CompileTargetingMode {
+    /**
+     * Always attempt compilation. Logs a warning if the compiler is unavailable.
+     */
+    ENABLED,
+
+    /**
+     * Never compile; always use the interpreter.
+     */
+    DISABLED,
+
+    /**
+     * Auto-detect: checks {@code javax.tools.ToolProvider.getSystemJavaCompiler() != null} at
+     * initialization. If the compiler is available, compilation is enabled; otherwise the
+     * interpreter is used silently. This is the default.
+     */
+    AUTO
+}

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/Config.java

@@ -57,6 +57,8 @@ public final class Config {
     static final String TARGET_URI_ENV_VAR_NAME = "FLAGD_TARGET_URI";
     static final String STREAM_RETRY_GRACE_PERIOD = "FLAGD_RETRY_GRACE_PERIOD";
     static final String REINITIALIZE_ON_ERROR_ENV_VAR_NAME = "FLAGD_REINITIALIZE_ON_ERROR";
+    static final String COMPILE_TARGETING_ENV_VAR_NAME = "FLAGD_COMPILE_TARGETING";
+    static final String DEFAULT_COMPILE_TARGETING = "auto";
 
     static final String RESOLVER_RPC = "rpc";
     static final String RESOLVER_IN_PROCESS = "in-process";
@@ -128,6 +130,26 @@ static Resolver fromValueProvider(Function<String, String> provider) {
         }
     }
 
+    static CompileTargetingMode compileTargetingFromString(String value) {
+        if (value == null) {
+            return CompileTargetingMode.AUTO;
+        }
+        switch (value.toLowerCase()) {
+            case "enabled":
+                return CompileTargetingMode.ENABLED;
+            case "disabled":
+                return CompileTargetingMode.DISABLED;
+            case "auto":
+                return CompileTargetingMode.AUTO;
+            default:
+                log.warn(
+                        "Unrecognized FLAGD_COMPILE_TARGETING value: '{}'. "
+                                + "Valid values are: enabled, disabled, auto. Defaulting to auto.",
+                        value);
+                return CompileTargetingMode.AUTO;
+        }
+    }
+
     /** intermediate interface to unify deprecated Evaluator and new Resolver. */
     public interface EvaluatorType {
         String asString();

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java

@@ -236,6 +236,23 @@ public class FlagdOptions {
     private boolean reinitializeOnError = Boolean.parseBoolean(
             fallBackToEnvOrDefault(Config.REINITIALIZE_ON_ERROR_ENV_VAR_NAME, Config.DEFAULT_REINITIALIZE_ON_ERROR));
 
+    /**
+     * !EXPERIMENTAL!
+     * Controls whether JsonLogic targeting rules are compiled into Java bytecode for improved
+     * evaluation performance.
+     * Requires the jdk.compiler module at runtime; falls back to interpreter mode if unavailable.
+     * In AUTO mode, the provider checks {@code javax.tools.ToolProvider.getSystemJavaCompiler() != null}
+     * at initialization to determine whether compilation is available.
+     * Compilation adds latency to the first evaluation of each rule (source generation, in-memory
+     * javac, class loading); subsequent evaluations are faster. This trade-off favors long-running
+     * services where rules are evaluated many times.
+     * Defaults to AUTO (compile if the compiler is available, otherwise use the interpreter).
+     * Only applicable in the in-process mode.
+     */
+    @Builder.Default
+    private CompileTargetingMode compileTargeting = Config.compileTargetingFromString(
+            fallBackToEnvOrDefault(Config.COMPILE_TARGETING_ENV_VAR_NAME, Config.DEFAULT_COMPILE_TARGETING));
+
     /**
      * The evaluator to use for flag evaluations. Defaults to {@code new FlagdCore()}. Only applicable in the in-process
      * mode

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/resolver/process/InProcessResolver.java

@@ -1,5 +1,6 @@
 package dev.openfeature.contrib.providers.flagd.resolver.process;
 
+import dev.openfeature.contrib.providers.flagd.CompileTargetingMode;
 import dev.openfeature.contrib.providers.flagd.FlagdOptions;
 import dev.openfeature.contrib.providers.flagd.resolver.Resolver;
 import dev.openfeature.contrib.providers.flagd.resolver.process.storage.FlagStore;
@@ -20,6 +21,7 @@
 import dev.openfeature.sdk.internal.TriConsumer;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
+import javax.tools.ToolProvider;
 import lombok.extern.slf4j.Slf4j;
 
 /**
@@ -51,7 +53,8 @@ public InProcessResolver(
             FlagdOptions options, TriConsumer<ProviderEvent, ProviderEventDetails, Structure> onConnectionEvent) {
         Evaluator evaluator = options.getEvaluator();
         if (evaluator == null) {
-            evaluator = new FlagdCore();
+            boolean compile = resolveCompileTargeting(options.getCompileTargeting());
+            evaluator = new FlagdCore(false, compile);
         }
         this.queueSource = getQueueSource(options);
         this.evaluator = evaluator;
@@ -190,4 +193,29 @@ static QueueSource getQueueSource(final FlagdOptions options) {
                 ? new FileQueueSource(options.getOfflineFlagSourcePath(), options.getOfflinePollIntervalMs())
                 : new SyncStreamQueueSource(options);
     }
+
+    /**
+     * Resolve the compile targeting mode to a boolean, performing auto-detection if needed.
+     */
+    static boolean resolveCompileTargeting(CompileTargetingMode mode) {
+        switch (mode) {
+            case ENABLED:
+                log.info("Targeting rule compilation enabled; requires the jdk.compiler module at runtime.");
+                return true;
+            case DISABLED:
+                log.info("Targeting rule compilation is disabled.");
+                return false;
+            case AUTO:
+            default:
+                boolean compilerAvailable = ToolProvider.getSystemJavaCompiler() != null;
+                if (compilerAvailable) {
+                    log.info("jdk.compiler detected; targeting rule compilation enabled automatically."
+                            + " Set FLAGD_COMPILE_TARGETING=disabled to disable.");
+                } else {
+                    log.info("jdk.compiler not detected; targeting rule compilation disabled."
+                            + " Set FLAGD_COMPILE_TARGETING=enabled to force (requires a JDK at runtime).");
+                }
+                return compilerAvailable;
+        }
+    }
 }

providers/flagd/src/test/java/dev/openfeature/contrib/providers/flagd/FlagdOptionsTest.java

@@ -54,6 +54,7 @@ void testDefaults() {
         assertEquals(0, builder.getKeepAlive());
         assertNull(builder.getDefaultAuthority());
         assertNull(builder.getClientInterceptors());
+        assertEquals(CompileTargetingMode.AUTO, builder.getCompileTargeting());
     }
 
     @Test
@@ -78,6 +79,7 @@ void testBuilderOptions() {
                 .keepAlive(1000)
                 .defaultAuthority("test-authority.sync.example.com")
                 .clientInterceptors(clientInterceptors)
+                .compileTargeting(CompileTargetingMode.ENABLED)
                 .build();
 
         assertEquals("https://hosted-flagd", flagdOptions.getHost());
@@ -95,6 +97,7 @@ void testBuilderOptions() {
         assertEquals(1000, flagdOptions.getKeepAlive());
         assertEquals("test-authority.sync.example.com", flagdOptions.getDefaultAuthority());
         assertEquals(clientInterceptors, flagdOptions.getClientInterceptors());
+        assertEquals(CompileTargetingMode.ENABLED, flagdOptions.getCompileTargeting());
     }
 
     @Test

tools/flagd-core/src/main/java/dev/openfeature/contrib/tools/flagd/core/FlagdCore.java

@@ -63,7 +63,7 @@ public class FlagdCore implements Evaluator {
      * Construct a FlagdCore instance.
      */
     public FlagdCore() {
-        this(false);
+        this(false, false);
     }
 
     /**
@@ -72,7 +72,17 @@ public FlagdCore() {
      * @param throwIfInvalid whether to throw an exception if flag configuration is invalid
      */
     public FlagdCore(boolean throwIfInvalid) {
-        this.operator = new Operator();
+        this(throwIfInvalid, false);
+    }
+
+    /**
+     * Construct a FlagdCore instance.
+     *
+     * @param throwIfInvalid whether to throw an exception if flag configuration is invalid
+     * @param compileTargeting whether to compile targeting rules for better performance
+     */
+    public FlagdCore(boolean throwIfInvalid, boolean compileTargeting) {
+        this.operator = new Operator(compileTargeting);
         this.throwIfInvalid = throwIfInvalid;
     }
 

tools/flagd-core/src/main/java/dev/openfeature/contrib/tools/flagd/core/targeting/Operator.java

@@ -19,17 +19,13 @@ public class Operator {
     static final String TARGET_KEY = "targetingKey";
     static final String TIME_STAMP = "timestamp";
 
-    static final String DISABLE_TARGETING_COMPILATION_ENV_VAR_NAME = "FLAGD_DISABLE_TARGETING_COMPILATION";
-
     private final JsonLogic jsonLogicHandler;
 
     /**
-     * Construct a targeting operator.
-     * Compiles targeting rules into native Java methods by default, unless the
-     * FLAGD_DISABLE_TARGETING_COMPILATION environment variable is set.
+     * Construct a targeting operator with compilation disabled.
      */
     public Operator() {
-        this(!Boolean.parseBoolean(System.getenv(DISABLE_TARGETING_COMPILATION_ENV_VAR_NAME)));
+        this(false);
     }
 
     /**