Add targeting-engine module: generic rules evaluation engine

Extracts a zero-dependency targeting rules engine into a new Maven module
(io.split:targeting-engine). Core algorithm, bucketing, and all matchers
are moved here, providing a foundation to be shared with the Android SDK.

- New module `targeting-engine/` added to root pom.xml
- 25 matcher/utility classes moved via git mv from client/ (history preserved):
  MurmurHash3, all value matchers (AllKeys, Between, Boolean, EqualTo,
  GreaterThanOrEqualTo, LessThanOrEqualTo), all semver matchers, all string
  matchers (StartsWithAnyOf, EndsWithAnyOf, ContainsAnyOf, RegularExpression),
  all set matchers (EqualToSet, PartOfSet, ContainsAllOfSet, ContainsAnyOfSet),
  Semver, Transformers, DependencyMatcher, PrerequisitesMatcher, WhitelistMatcher
- New interfaces and implementations written from scratch:
  TargetingEngine, TargetingEngineImpl, EvaluationContext, EvaluationResult,
  EvaluationLabels, Bucketer, Matcher, CombiningMatcher, AttributeMatcher,
  UserDefinedSegmentMatcher, RuleBasedSegmentMatcher, Logger,
  VersionedExceptionWrapper, all model classes (TargetingRule, Condition,
  ConditionType, Partition, Prerequisite, DataType)
- Packages updated: io.split.engine.matchers → io.split.rules.matchers
- Removed Guava and SLF4J dependencies from moved classes
- 37 TDD tests pass (BucketerTest, TargetingEngineImplTest, AllKeysMatcherTest,
  BetweenMatcherTest, BooleanMatcherTest, SemverTest)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: gthea

pom.xml

@@ -64,6 +64,7 @@
         <maven.compiler.target>1.8</maven.compiler.target>
     </properties>
     <modules>
+        <module>targeting-engine</module>
         <module>pluggable-storage</module>
         <module>redis-wrapper</module>
         <module>testing</module>

targeting-engine/pom.xml

@@ -0,0 +1,50 @@
+<?xml version="1.0"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.split.client</groupId>
+        <artifactId>java-client-parent</artifactId>
+        <version>4.18.3</version>
+    </parent>
+
+    <version>4.18.3</version>
+    <artifactId>targeting-engine</artifactId>
+    <packaging>jar</packaging>
+    <name>Targeting Engine</name>
+    <description>A generic, zero-dependency targeting rules engine extracted from the Split Java SDK</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.13.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>5.14.2</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.3</version>
+                <configuration>
+                    <source>${maven.compiler.source}</source>
+                    <target>${maven.compiler.target}</target>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.2.5</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>

targeting-engine/src/main/java/io/split/rules/bucketing/Bucketer.java

@@ -0,0 +1,78 @@
+package io.split.rules.bucketing;
+
+import io.split.rules.model.Partition;
+
+import java.util.List;
+
+/**
+ * Hashes keys into buckets and selects treatments from partition lists.
+ */
+public final class Bucketer {
+    private static final int ALGO_LEGACY = 1;
+    private static final int ALGO_MURMUR = 2;
+    private static final String CONTROL = "control";
+
+    /**
+     * Returns the treatment for the given key, seed, partitions, and algorithm.
+     * Returns "control" if no partition matches.
+     */
+    public static String getTreatment(String key, int seed, List<Partition> partitions, int algo) {
+        if (partitions.isEmpty()) {
+            return CONTROL;
+        }
+        if (hundredPercentOneTreatment(partitions)) {
+            return partitions.get(0).treatment;
+        }
+        return selectTreatment(bucket(hash(key, seed, algo)), partitions);
+    }
+
+    /**
+     * Returns a bucket between 1 and 100, inclusive.
+     */
+    public static int getBucket(String key, int seed, int algo) {
+        return bucket(hash(key, seed, algo));
+    }
+
+    static long hash(String key, int seed, int algo) {
+        switch (algo) {
+            case ALGO_MURMUR:
+                return murmurHash(key, seed);
+            case ALGO_LEGACY:
+            default:
+                return legacyHash(key, seed);
+        }
+    }
+
+    static long murmurHash(String key, int seed) {
+        return MurmurHash3.murmurhash3_x86_32(key, 0, key.length(), seed);
+    }
+
+    static int legacyHash(String key, int seed) {
+        int h = 0;
+        for (int i = 0; i < key.length(); i++) {
+            h = 31 * h + key.charAt(i);
+        }
+        return h ^ seed;
+    }
+
+    static int bucket(long hash) {
+        return (int) (Math.abs(hash % 100) + 1);
+    }
+
+    private static String selectTreatment(int bucket, List<Partition> partitions) {
+        int covered = 0;
+        for (Partition partition : partitions) {
+            covered += partition.size;
+            if (covered >= bucket) {
+                return partition.treatment;
+            }
+        }
+        return CONTROL;
+    }
+
+    private static boolean hundredPercentOneTreatment(List<Partition> partitions) {
+        return partitions.size() == 1 && partitions.get(0).size == 100;
+    }
+
+    private Bucketer() {}
+}

…a/io/split/client/utils/MurmurHash3.java …o/split/rules/bucketing/MurmurHash3.javaclient/src/main/java/io/split/client/utils/MurmurHash3.java renamed to targeting-engine/src/main/java/io/split/rules/bucketing/MurmurHash3.java client/src/main/java/io/split/client/utils/MurmurHash3.java renamed to targeting-engine/src/main/java/io/split/rules/bucketing/MurmurHash3.java

@@ -1,4 +1,4 @@
-package io.split.client.utils;
+package io.split.rules.bucketing;
 
 /**
  * The MurmurHash3 algorithm was created by Austin Appleby and placed in the public domain.

targeting-engine/src/main/java/io/split/rules/engine/EvaluationContext.java

@@ -0,0 +1,25 @@
+package io.split.rules.engine;
+
+import java.util.Map;
+
+/**
+ * Provides recursive evaluation and segment membership checks to matchers.
+ * Each SDK implements this interface to bridge to its own storage and evaluator.
+ */
+public interface EvaluationContext {
+
+    /**
+     * Evaluates a targeting rule by name. Used by DependencyMatcher and PrerequisitesMatcher.
+     */
+    EvaluationResult evaluate(String matchingKey, String bucketingKey, String ruleName, Map<String, Object> attributes);
+
+    /**
+     * Checks if the given key is a member of a standard segment.
+     */
+    boolean isInSegment(String segmentName, String key);
+
+    /**
+     * Checks if the given key is a member of a rule-based segment.
+     */
+    boolean isInRuleBasedSegment(String segmentName, String key, String bucketingKey, Map<String, Object> attributes);
+}

targeting-engine/src/main/java/io/split/rules/engine/EvaluationLabels.java

@@ -0,0 +1,14 @@
+package io.split.rules.engine;
+
+public final class EvaluationLabels {
+    public static final String NOT_IN_SPLIT = "not in split";
+    public static final String DEFAULT_RULE = "default rule";
+    public static final String KILLED = "killed";
+    public static final String DEFINITION_NOT_FOUND = "definition not found";
+    public static final String EXCEPTION = "exception";
+    public static final String UNSUPPORTED_MATCHER = "targeting rule type unsupported by sdk";
+    public static final String PREREQUISITES_NOT_MET = "prerequisites not met";
+    public static final String NOT_READY = "not ready";
+
+    private EvaluationLabels() {}
+}

targeting-engine/src/main/java/io/split/rules/engine/EvaluationResult.java

@@ -0,0 +1,25 @@
+package io.split.rules.engine;
+
+public final class EvaluationResult {
+    public final String treatment;
+    public final String label;
+    public final Long version;
+    public final String config;
+    public final boolean impressionsDisabled;
+
+    public EvaluationResult(String treatment, String label) {
+        this(treatment, label, null, null, false);
+    }
+
+    public EvaluationResult(String treatment, String label, Long version) {
+        this(treatment, label, version, null, false);
+    }
+
+    public EvaluationResult(String treatment, String label, Long version, String config, boolean impressionsDisabled) {
+        this.treatment = treatment;
+        this.label = label;
+        this.version = version;
+        this.config = config;
+        this.impressionsDisabled = impressionsDisabled;
+    }
+}

targeting-engine/src/main/java/io/split/rules/engine/TargetingEngine.java

@@ -0,0 +1,15 @@
+package io.split.rules.engine;
+
+import io.split.rules.model.TargetingRule;
+
+import java.util.Map;
+
+/**
+ * Evaluates a targeting rule against a key and attributes.
+ * This is the core contract of the targeting engine.
+ */
+public interface TargetingEngine {
+    EvaluationResult evaluate(String matchingKey, String bucketingKey,
+                              TargetingRule rule, Map<String, Object> attributes,
+                              EvaluationContext context);
+}

targeting-engine/src/main/java/io/split/rules/engine/TargetingEngineImpl.java

@@ -0,0 +1,86 @@
+package io.split.rules.engine;
+
+import io.split.rules.bucketing.Bucketer;
+import io.split.rules.exceptions.VersionedExceptionWrapper;
+import io.split.rules.matchers.PrerequisitesMatcher;
+import io.split.rules.model.Condition;
+import io.split.rules.model.ConditionType;
+import io.split.rules.model.TargetingRule;
+
+import java.util.Map;
+
+public final class TargetingEngineImpl implements TargetingEngine {
+
+    @Override
+    public EvaluationResult evaluate(String matchingKey, String bucketingKey,
+                                     TargetingRule rule, Map<String, Object> attributes,
+                                     EvaluationContext context) {
+        try {
+            return evaluateInternal(matchingKey, bucketingKey, rule, attributes, context);
+        } catch (VersionedExceptionWrapper e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    private EvaluationResult evaluateInternal(String matchingKey, String bucketingKey,
+                                              TargetingRule rule, Map<String, Object> attributes,
+                                              EvaluationContext context) throws VersionedExceptionWrapper {
+        try {
+            String config = getConfig(rule, rule.defaultTreatment());
+
+            // 1. Killed rule → return default treatment
+            if (rule.killed()) {
+                return new EvaluationResult(rule.defaultTreatment(), EvaluationLabels.KILLED,
+                        rule.changeNumber(), config, rule.impressionsDisabled());
+            }
+
+            // 2. Bucketing key resolution
+            String bk = bucketingKey != null ? bucketingKey : matchingKey;
+
+            // 3. Prerequisites check
+            PrerequisitesMatcher prereqMatcher = new PrerequisitesMatcher(rule.prerequisites());
+            if (!prereqMatcher.match(matchingKey, bk, attributes, context)) {
+                return new EvaluationResult(rule.defaultTreatment(), EvaluationLabels.PREREQUISITES_NOT_MET,
+                        rule.changeNumber(), config, rule.impressionsDisabled());
+            }
+
+            // 4. Iterate conditions
+            boolean inRollout = false;
+            for (Condition condition : rule.conditions()) {
+
+                // 4a. Traffic allocation check (once, before first ROLLOUT condition)
+                if (!inRollout && condition.conditionType() == ConditionType.ROLLOUT) {
+                    if (rule.trafficAllocation() < 100) {
+                        int bucket = Bucketer.getBucket(bk, rule.trafficAllocationSeed(), rule.algo());
+                        if (bucket > rule.trafficAllocation()) {
+                            config = getConfig(rule, rule.defaultTreatment());
+                            return new EvaluationResult(rule.defaultTreatment(), EvaluationLabels.NOT_IN_SPLIT,
+                                    rule.changeNumber(), config, rule.impressionsDisabled());
+                        }
+                    }
+                    inRollout = true;
+                }
+
+                // 4b. Condition match → select treatment
+                if (condition.matcher().match(matchingKey, bucketingKey, attributes, context)) {
+                    String treatment = Bucketer.getTreatment(bk, rule.seed(), condition.partitions(), rule.algo());
+                    config = getConfig(rule, treatment);
+                    return new EvaluationResult(treatment, condition.label(),
+                            rule.changeNumber(), config, rule.impressionsDisabled());
+                }
+            }
+
+            // 5. No condition matched → default rule
+            config = getConfig(rule, rule.defaultTreatment());
+            return new EvaluationResult(rule.defaultTreatment(), EvaluationLabels.DEFAULT_RULE,
+                    rule.changeNumber(), config, rule.impressionsDisabled());
+
+        } catch (Exception e) {
+            throw new VersionedExceptionWrapper(e, rule.changeNumber());
+        }
+    }
+
+    private String getConfig(TargetingRule rule, String treatment) {
+        return rule.configurations() != null ? rule.configurations().get(treatment) : null;
+    }
+}

targeting-engine/src/main/java/io/split/rules/exceptions/VersionedExceptionWrapper.java

@@ -0,0 +1,19 @@
+package io.split.rules.exceptions;
+
+public class VersionedExceptionWrapper extends Exception {
+    private final Exception _wrappedException;
+    private final Long _version;
+
+    public VersionedExceptionWrapper(Exception wrappedException, Long version) {
+        _wrappedException = wrappedException;
+        _version = version;
+    }
+
+    public Exception wrappedException() {
+        return _wrappedException;
+    }
+
+    public Long version() {
+        return _version;
+    }
+}