feat: add v4 evaluation response types to provider library

src/main/java/com/octopus/openfeature/provider/v4/ClientSideCondition.java

@@ -0,0 +1,33 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+
+/**
+ * Base type for a client-side rule condition, selected from the camelCase {@code type} discriminator
+ * when deserializing a v4 evaluation response. These types model the wire shape only.
+ *
+ * <p>A discriminator this version of the provider does not recognise — or an absent one —
+ * deserializes to {@link UnknownCondition} rather than failing, so a condition type
+ * introduced by a newer server degrades safely on an older client.
+ *
+ * <p>The conditions sit alongside the rest of the v4 types rather than in a {@code conditions}
+ * sub-package as the .NET provider has them. Java package access is not hierarchical, so a
+ * package-private condition there would be invisible to {@link ClientSideRule} in this package, and
+ * following that layout would mean making every condition public — part of the library's supported
+ * API, which is what keeping these types package-private is meant to avoid.
+ */
+@JsonTypeInfo(
+        use = JsonTypeInfo.Id.NAME,
+        include = JsonTypeInfo.As.PROPERTY,
+        property = "type",
+        visible = true,
+        defaultImpl = UnknownCondition.class
+)
+@JsonSubTypes({
+        @JsonSubTypes.Type(value = PercentageByContextCondition.class, name = ConditionTypeNames.PERCENTAGE_BY_CONTEXT),
+        @JsonSubTypes.Type(value = ContextAttributeIsOneOfCondition.class, name = ConditionTypeNames.CONTEXT_ATTRIBUTE_IS_ONE_OF),
+        @JsonSubTypes.Type(value = ContextAttributeIsNotOneOfCondition.class, name = ConditionTypeNames.CONTEXT_ATTRIBUTE_IS_NOT_ONE_OF)
+})
+abstract class ClientSideCondition {
+}

src/main/java/com/octopus/openfeature/provider/v4/ClientSideRule.java

@@ -0,0 +1,32 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+/**
+ * A named rule the provider library still has to evaluate on the client side. The rule matches when
+ * every one of its conditions matches.
+ */
+final class ClientSideRule {
+    private final String name;
+    private final List<ClientSideCondition> conditions;
+
+    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
+    ClientSideRule(
+            @JsonProperty(value = "name", required = true) String name,
+            @JsonProperty(value = "conditions", required = true) List<ClientSideCondition> conditions
+    ) {
+        this.name = name;
+        this.conditions = List.copyOf(conditions);
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public List<ClientSideCondition> getConditions() {
+        return conditions;
+    }
+}

src/main/java/com/octopus/openfeature/provider/v4/ConditionTypeNames.java

@@ -0,0 +1,14 @@
+package com.octopus.openfeature.provider.v4;
+
+/**
+ * Discriminator values for the polymorphic v4 client-side conditions. These mirror the values in the
+ * evaluation response, so they must not drift from the server.
+ */
+final class ConditionTypeNames {
+    static final String CONTEXT_ATTRIBUTE_IS_NOT_ONE_OF = "context-attribute-is-not-one-of";
+    static final String CONTEXT_ATTRIBUTE_IS_ONE_OF = "context-attribute-is-one-of";
+    static final String PERCENTAGE_BY_CONTEXT = "percentage-by-context";
+
+    private ConditionTypeNames() {
+    }
+}

src/main/java/com/octopus/openfeature/provider/v4/ContextAttributeIsNotOneOfCondition.java

@@ -0,0 +1,33 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+/**
+ * Matches when the context attribute {@code key} is not one of {@code values}.
+ */
+@JsonIgnoreProperties("type") // The discriminator is visible to subtypes; this type does not model it.
+final class ContextAttributeIsNotOneOfCondition extends ClientSideCondition {
+    private final String key;
+    private final List<String> values;
+
+    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
+    ContextAttributeIsNotOneOfCondition(
+            @JsonProperty(value = "key", required = true) String key,
+            @JsonProperty(value = "values", required = true) List<String> values
+    ) {
+        this.key = key;
+        this.values = List.copyOf(values);
+    }
+
+    public String getKey() {
+        return key;
+    }
+
+    public List<String> getValues() {
+        return values;
+    }
+}

src/main/java/com/octopus/openfeature/provider/v4/ContextAttributeIsOneOfCondition.java

@@ -0,0 +1,33 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+/**
+ * Matches when the context attribute {@code key} is one of {@code values}.
+ */
+@JsonIgnoreProperties("type") // The discriminator is visible to subtypes; this type does not model it.
+final class ContextAttributeIsOneOfCondition extends ClientSideCondition {
+    private final String key;
+    private final List<String> values;
+
+    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
+    ContextAttributeIsOneOfCondition(
+            @JsonProperty(value = "key", required = true) String key,
+            @JsonProperty(value = "values", required = true) List<String> values
+    ) {
+        this.key = key;
+        this.values = List.copyOf(values);
+    }
+
+    public String getKey() {
+        return key;
+    }
+
+    public List<String> getValues() {
+        return values;
+    }
+}

src/main/java/com/octopus/openfeature/provider/v4/PercentageByContextCondition.java

@@ -0,0 +1,24 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Matches when the OpenFeature targeting key falls within the {@code percentage}% rollout.
+ */
+@JsonIgnoreProperties("type") // The discriminator is visible to subtypes; this type does not model it.
+final class PercentageByContextCondition extends ClientSideCondition {
+    private final int percentage;
+
+    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
+    PercentageByContextCondition(
+            @JsonProperty(value = "percentage", required = true) int percentage
+    ) {
+        this.percentage = percentage;
+    }
+
+    public int getPercentage() {
+        return percentage;
+    }
+}

src/main/java/com/octopus/openfeature/provider/v4/ServerSideEvaluation.java

@@ -0,0 +1,62 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * A single feature flag as returned by the OctoToggle v4 evaluations endpoint. The endpoint returns
+ * an array of these.
+ *
+ * <p>A flag is returned in one of two shapes:
+ * <ul>
+ * <li>Resolved by the server — {@code value} and {@code reason} are populated.</li>
+ * <li>Deferred to the client — {@code evaluationKey} and {@code rules} are populated and the
+ * provider library must evaluate the remaining client-side conditions.</li>
+ * </ul>
+ * Properties that do not apply to the returned shape are omitted from the JSON.
+ */
+final class ServerSideEvaluation {
+    private final String slug;
+    private final Boolean value;
+    private final String reason;
+    private final String evaluationKey;
+    private final List<ClientSideRule> rules;
+
+    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
+    ServerSideEvaluation(
+            @JsonProperty(value = "slug", required = true) String slug,
+            @JsonProperty("value") Boolean value,
+            @JsonProperty("reason") String reason,
+            @JsonProperty("evaluationKey") String evaluationKey,
+            @JsonProperty("rules") List<ClientSideRule> rules
+    ) {
+        this.slug = slug;
+        this.value = value;
+        this.reason = reason;
+        this.evaluationKey = evaluationKey;
+        this.rules = rules == null ? null : List.copyOf(rules);
+    }
+
+    public String getSlug() {
+        return slug;
+    }
+
+    public Optional<Boolean> getValue() {
+        return Optional.ofNullable(value);
+    }
+
+    public Optional<String> getReason() {
+        return Optional.ofNullable(reason);
+    }
+
+    public Optional<String> getEvaluationKey() {
+        return Optional.ofNullable(evaluationKey);
+    }
+
+    public Optional<List<ClientSideRule>> getRules() {
+        return Optional.ofNullable(rules);
+    }
+}

src/main/java/com/octopus/openfeature/provider/v4/UnknownCondition.java

@@ -0,0 +1,33 @@
+package com.octopus.openfeature.provider.v4;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.Optional;
+
+/**
+ * A client-side condition whose {@code type} discriminator this version of the provider does not
+ * recognise, or which carried no discriminator at all. Rather than failing the whole evaluation
+ * response, an unrecognised condition is preserved as this type. It always evaluates to
+ * {@code false}, so a rule containing an unknown condition can never match — a newer server
+ * capability is safely treated as "not met" by an older client.
+ *
+ * <p>The raw payload of an unknown condition is not retained, only its discriminator.
+ */
+final class UnknownCondition extends ClientSideCondition {
+    private final String type;
+
+    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
+    UnknownCondition(
+            @JsonProperty("type") String type
+    ) {
+        this.type = type;
+    }
+
+    /**
+     * The unrecognised discriminator value, or empty if none was present.
+     */
+    public Optional<String> getType() {
+        return Optional.ofNullable(type);
+    }
+}

src/test/java/com/octopus/openfeature/provider/TestObjectMapper.java

@@ -0,0 +1,17 @@
+package com.octopus.openfeature.provider;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+/**
+ * Exposes the provider's package-private {@link OctopusObjectMapper} to tests in other packages, so
+ * they can exercise deserialization with the same mapper the client uses in production rather than
+ * a re-declared copy that could drift from it.
+ *
+ * <p>Test-only: this lives in the test sources and is never published.
+ */
+public final class TestObjectMapper {
+    public static final ObjectMapper INSTANCE = OctopusObjectMapper.INSTANCE;
+
+    private TestObjectMapper() {
+    }
+}