Skip to content

Return read-only JSON flag values with exact integers - #13484

Draft
leoromanovsky wants to merge 3 commits into
masterfrom
leo.romanovsky/ffe-json-frozen-values
Draft

leoromanovsky wants to merge 3 commits into
masterfrom
leo.romanovsky/ffe-json-frozen-values

Conversation

@leoromanovsky

@leoromanovsky leoromanovsky commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What Does This Do

  • A JSON flag evaluation returns a shared, read-only Value that is built once when the configuration is parsed. Before this change, each evaluation converted the whole variant tree to a new Value.
  • Integers in JSON variant values are returned exactly. For example, 5 is returned as 5 and not as 5.0, and integers up to Long.MAX_VALUE do not lose precision.
  • The parsed tree of a JSON variant is not kept next to the frozen tree, so the extra memory stays small.

Motivation

Customers that use many JSON flags pay a per-evaluation cost that grows with the variant size. Before this change, one evaluation of a JSON variant with about 700 nodes takes about 13 µs and allocates about 57 KB (see Results).

The JSON number handling is also a correctness bug. The parser reads every JSON number as a double. So integer fields come back as Double, and integer IDs above 2^53 change value.

Changes

  • ufc/FrozenValues (new package-private class): converts a parsed JSON tree to a Value that cannot change.
    • Each object is a FrozenStructure, a MutableStructure over an unmodifiable map. It does not override equals, hashCode or canEqual, so equality with Value.objectToValue does not change. getValue returns the shared child without a copy.
    • Each list is an unmodifiable list.
    • FrozenStructure.asObjectMap() builds the plain-map form once and then shares it. The map and all of its nested maps and lists are unmodifiable.
    • LONG_VALUES tells whether the loaded OpenFeature SDK has Value(Long). SDK 1.22.0 added it.
  • ufc/Variant: new field frozenValue, and a constructor that takes it. The parser sets it for a JSON flag whose value is an object or an array.
  • UniversalFlagConfigParser:
    • Integers under flags.<flag>.variations.<key>.value are read as Integer or Long. Larger integers stay Double, as before. The scope follows positions, so a flag key such as "variations" does not change it.
    • With an OpenFeature SDK older than 1.22.0, integers that need a Long stay Double, as before. Such an SDK rejects a Long value with TypeMismatchError, which would reject the whole configuration.
    • A JSON object or array variant is frozen in toVariant. Its plain form (the shared asObjectMap() map) replaces the parsed tree as Variant.value, so the parsed containers are not kept as well.
    • For non-JSON flags, variant integers go back to Double, also when they are nested in a container, so these flags do not change.
  • FlagEvaluator.resolveVariant: returns frozenValue for Value targets. Other targets use mapValue, as before.
  • README.md: two notes under "Migrating from earlier versions" about read-only values and exact integers.
  • Tests:
    • New: FlagEvaluatorJsonValueTest. It checks that the instance is shared, that the value is equal to Value.objectToValue, that integers are exact (also through the parseJsonApi envelope and for a flag keyed "variations"), that the value cannot change, that array variants work, that condition values and non-JSON flags stay Double, and that integers beyond the long range stay Double.
    • Changed: CanonicalFixtureTest. The shared fixture test-json-config-flag.json expects "integer": 1 and "float": 1.0. The test normalized the expected integers to doubles, to match the old parser. It now keeps exact integers for the results and the default values of JSON cases.
    • dd-openfeature tests: 1573 tests, 1567 passed, 6 skipped, 0 failed.
    • With OpenFeature SDK 1.21.0 on the classpath, a configuration with a JSON variant {"id":3000000000} parses. Before the LONG_VALUES check, the parse threw TypeMismatchError.

Results

Local JMH benchmark (not in a repository yet), dd-openfeature 1.69.0 compared with this branch, through the OpenFeature client (getObjectValue). JMH SampleTime, 2 forks × 5 iterations of 3 s, after 5 warm-up iterations of 2 s. macOS arm64, JDK 17. The two versions ran one after the other for each scenario. These numbers are from the first commit. The second commit does not change the evaluation path. The allocation values are exact. The load average was 5–26 during the run, so the absolute times are higher than on an idle host. The error is ±1–4% of the mean.

Benchmark Scenario 1.69.0: mean / p50 / p99 / alloc This branch: mean / p50 / p99 / alloc Mean speedup
evalPrepared json-small (~8 nodes) 1,123 ns / 1,000 ns / 2,372 ns / 2,262 B 1,022 ns / 917 ns / 2,292 ns / 1,528 B 1.1×
evalPrepared json-medium (~160 nodes) 3,815 ns / 3,456 ns / 8,656 ns / 11,842 B 1,037 ns / 916 ns / 2,416 ns / 1,523 B 3.7×
evalPrepared json-large (~700 nodes) 13,196 ns / 11,536 ns / 29,056 ns / 57,005 B 965 ns / 875 ns / 2,332 ns / 1,649 B 13.7×
evalAndRead json-small 1,203 ns / 1,084 ns / 2,500 ns / 2,984 B 1,032 ns / 917 ns / 2,540 ns / 1,645 B 1.2×
evalAndRead json-medium 6,157 ns / 5,832 ns / 9,040 ns / 21,792 B 1,201 ns / 917 ns / 2,832 ns / 1,608 B 5.1×
evalAndRead json-large 26,075 ns / 25,056 ns / 38,656 ns / 116,995 B 1,010 ns / 917 ns / 2,416 ns / 1,626 B 25.8×
evalPrepared mixed (all flag types) 1,711 ns / 1,290 ns / 13,458 ns / 3,228 B 1,342 ns / 1,166 ns / 3,040 ns / 1,887 B 1.3×
evalAndRead mixed 2,242 ns / 1,416 ns / 27,616 ns / 4,608 B 1,458 ns / 1,292 ns / 3,416 ns / 1,919 B 1.5×
  • evalAndRead adds asStructure().asObjectMap(), which applications often call.
  • With this branch, a JSON flag costs about the same at every variant size: about 1 µs and 1.5–1.7 KB per call, which is the cost of the OpenFeature client and the provider. Before, the cost grew with the variant size.
  • mixed uses a realistic mix of all flag types (12% JSON). It shows that the other flag types do not get slower.

Retained memory of the JSON variants, measured with JOL (GraphLayout.totalSize() of all Variant.value and Variant.frozenValue objects). The synthetic configuration has 300 JSON flags with 3 variants each. Each variant has 40 scalar fields, a nested object with 10 fields, and an array with 20 strings.

Version Variant memory After asObjectMap() on each variant
1.69.0 4,249 KB 4,249 KB
This branch 6,947 KB 6,947 KB

The first commit kept the parsed tree next to the frozen tree: 7,228 KB, and 9,323 KB after asObjectMap().

Decisions

  • Build at parse time, not on first use. The cost is paid once for each configuration. A lazy build would save memory only for variants that are never served.
  • Keep the plain form, not the parsed tree. For a JSON flag, the evaluator only returns frozenValue, so the parsed tree is no longer read. The plain form is the shared asObjectMap() map, so Variant.value stays an equal plain tree without a second copy.
  • Check the SDK for Long support instead of requiring a newer SDK. The provider declares OpenFeature SDK 1.23.0, but Maven can resolve an older SDK that an application declares directly. With an older SDK, large integers stay Double, as before this change. The check runs once, when the class loads, and only the parser reads it.
  • Use OpenFeature's MutableStructure over an unmodifiable map, not ImmutableStructure. ImmutableStructure.getValue deep-clones on each call, so each read by the application would be a full copy. MutableStructure keeps the type and the equals behavior of today's result.
  • Exact integers only in JSON variant values. Other UFC code expects Double (shard ranges, serial IDs, feature values, numeric conditions). Changing only the variant scope keeps that code as it is.
  • Integer or Long, not BigInteger. Structure.convertValue cannot convert a BigInteger, so asObjectMap() would throw. Integers outside the Long range stay Double, as before.

Behavior changes

  • A caller that changes a returned JSON structure, list, or asObjectMap() map now gets UnsupportedOperationException. Before this change, each evaluation returned a new mutable copy. asMap() still returns a new HashMap copy.
  • A hook that changes the value in after makes the evaluation return the default value with the GENERAL error code.
  • asObjectMap(), Value.asObject() and Value.equals see 5 (Integer) instead of 5.0 (Double) for JSON integers. This fixes the bug, but it can change what an application serializes or compares. For example, value.equals(new Value(5.0)) is now false.
  • Value.asInteger() on an integer above 2^31-1 now wraps (Long.intValue()). Before, the Double saturated.
  • The README notes under "Migrating from earlier versions" describe these changes.

Contributor Checklist

Each evaluation of a JSON flag converted the whole variant tree to a new
OpenFeature Value. The cost grew with the variant size: about 21 us and
83 KB for a 712-node variant.

The parser now builds one Value for each JSON object or array variant.
Evaluations return that instance. Its structures are MutableStructure
over unmodifiable maps and its lists are unmodifiable, so callers cannot
change it, and equals is the same as Value.objectToValue. The plain-map
form is built once and shared.

Integers in JSON variant values now stay Integer or Long instead of
Double, so 5 is returned as 5 and integers above 2^53 stay exact.
Scalar flags keep Double values.
@leoromanovsky leoromanovsky added type: feature Enhancements and improvements tag: performance Performance related changes tag: ai generated Largely based on code generated by an AI or LLM comp: openfeature OpenFeature crucible: reviewing A Crucible review has started; this PR has reviewer attention. labels Nov 16, 2026
@datadog-datadog-prod-us1

This comment has been minimized.

@dd-octo-sts

dd-octo-sts Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite Status
Startup 🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results
Scenario Candidate master Δ (95% CI of mean)
startup:insecure-bank:iast:Agent 14.88 s 14.68 s [+0.7%; +2.0%] (maybe worse)
startup:insecure-bank:tracing:Agent 13.60 s 13.68 s [-1.2%; +0.1%] (no difference)
startup:petclinic:appsec:Agent 17.77 s 17.72 s [-0.5%; +1.0%] (no difference)
startup:petclinic:iast:Agent 17.67 s 17.73 s [-1.4%; +0.7%] (no difference)
startup:petclinic:profiling:Agent 17.46 s 17.32 s [-0.2%; +1.9%] (no difference)
startup:petclinic:sca:Agent 17.85 s 17.62 s [+0.4%; +2.3%] (maybe worse)
startup:petclinic:tracing:Agent 16.69 s 16.93 s [-2.6%; -0.2%] (maybe better)

Commit: 985c7506 · CI Pipeline · Benchmarking Platform UI


Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

@leoromanovsky leoromanovsky removed the crucible: reviewing A Crucible review has started; this PR has reviewer attention. label Nov 16, 2026
- Keep Long values only when the loaded OpenFeature SDK supports them.
  SDK 1.21.0 and older reject a Long with TypeMismatchError, which
  rejected the whole configuration.
- Freeze JSON variants in the parser, and store the frozen tree's plain
  form as Variant.value. The parsed tree is no longer kept as well.
- Make the parser scope follow positions, so a flag keyed "variations"
  keeps exact integers.
- Change nested integers of non-JSON flags back to Double, as before.
- Use one number model for JSON fixture defaults and results.
- Size maps exactly, and make FrozenValues package-private.
- Correct javadoc, and document the read-only values and exact integers.
- Add tests for the CDN envelope, the "variations" key, non-JSON flags
  and integers beyond the long range.
@leoromanovsky leoromanovsky changed the title Share frozen JSON variant values and keep their integers exact Return read-only JSON flag values with exact integers Nov 16, 2026
Handle non-JSON flags first in toVariant, use assertNull, and shorten the javadoc. No behavior change.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp: openfeature OpenFeature tag: ai generated Largely based on code generated by an AI or LLM tag: performance Performance related changes type: feature Enhancements and improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant