test(ofrep): adopt the OpenFeature Provider TCK

[aepfli]

Stacked on #1830. Base is feat/provider-tck, so this diff shows only the new work. Review
#1830 first — it describes the suite, the adoption API and the capability vocabulary, and none of
that is repeated here.

Part of #1829 and open-feature/spec#417.

The OFREP provider under the conformance suite. Three files: one test class, a Compose file, and the
test dependency in providers/ofrep/pom.xml.

No new infrastructure. The same flagd-testbed image the flagd suites use, exposing 8016 (OFREP)
and 8080 (launchpad), no pinned host ports.

providers/ofrep's e2e package is gone — the conformance suite had been its only member. That
is the nesting argument in its clearest form: the adoption was filed under a category the module did
not have. What remains is …/ofrep/tck/OfrepTest.java, selected by **/tck/*.java in both the default
build's exclusions and the tck profile's includes.

What it declares

Declared: @object, @variants, @targeting, @standard-reasons, @string-typing,
@fully-typed-values.

The last two hold for a mechanical reason worth stating: handleResolved admits a value only on an
exact type.isInstance check, so String.class.isInstance of a Boolean, Integer or Double is
false and the result is TYPE_MISMATCH rather than toString(). The same strictness is what loses
it @numeric-coercion.

Withheld: @lifecycle, @reinitialization, @events, @stale, @configuration-change,
@unavailable, @disabled-flags, @numeric-coercion. (@large-integers is refused by the
implementation for every Java provider — a 32-bit Integer accessor — rather than withheld here.)

Six of those share one root cause: OfrepProvider is a bare FeatureProvider with no lifecycle of
its own. It holds no state, opens no stream, runs no poll loop and does not override initialize() —
every evaluation is a fresh, independent HTTP POST. There is nothing in it that could observe a
backend transition, let alone report one. Declaring @lifecycle would make the readiness scenario
pass vacuously: the PROVIDER_READY a client sees is the SDK's, emitted identically for
NoOpProvider and for a provider aimed at a dead port.

Two are more interesting, and both were measured rather than read off the source:

• @numeric-coercion is withheld and carries no deviation. Its three scenarios test all three
  cases and a provider declaring the tag must pass all three; this one passes one, and gets it right
  for the wrong reason — 0.5 as an integer is rejected because it is a Double, not because it is
  fractional. Both lossless cases fail on the same exact-instance check. No deviation accompanies it
  deliberately: Appendix F is explicit that this is the one capability the specification does not
  define — OpenFeature has a single number type, the rule is borrowed from flagd's ADR, and "a
  provider that behaves differently is not violating the specification".
• @disabled-flags is withheld and does carry a deviation, which is the opposite call, and the
  difference is where the rule lives. flagd's OFREP endpoint answers a disabled flag with 200 and
  {"key":…,"reason":"DISABLED"} and no value member. That is well-formed OFREP — the
  codeDefaultFlag member schema, described as "A flag evaluation that defers to the code default
  value … The provider must use the code default value when processing this response" — and
  handleResolved reaches its responseValue == null branch and reports FLAG_NOT_FOUND, discarding
  the reason it parsed one field earlier. So a MUST in the protocol this provider implements is
  unmet, and the gap is wider than the four rows that found it: every codeDefaultFlag response is
  reported to the application as a failure on an evaluation that succeeded.

That last one is the declaration on this branch the settled guidance would shape differently, and it
is recorded rather than quietly left. KnownDeviation prefers declared-and-failing and confines
withheld-and-skipped to a provider that cannot attempt the behaviour at all — and this provider does
attempt it. Flagging it explicitly because it is the kind of call a reviewer should get to make.

The backend stack

One Compose file serves both conformance suites in this repository, at
tools/flagd-testbed/docker-compose.yaml: the unmodified flagd-testbed image, service backend,
publishing 8013, 8015, 8016 and 8080 with no host port bindings — the suite requires dynamically
mapped ports and discovers them after startup. Each suite asks the harness only for the ports it
needs, so the extra ones cost nothing. It is a plain directory rather than a Maven module, so neither
provider reaches into the other's tree; both composeFile() overrides climb out of their module and
say why.

It used to be one file per adoption. Four hand-maintained copies across the four languages had
drifted on the one field that decides what is being tested — the image tag — which is exactly the kind
of divergence a conformance suite exists to prevent, occurring in the suite itself. That is now
resolved: all four languages run flagd-testbed:v3.10.1, the current release, aligned up from the
v3.8.0 three of them were pinned to.

The bump fixes nothing on its own, which is worth saying because a version bump reads like a fix.
flagd-testbed#392 and
#394 are both still open, so v3.10.1 carries
neither the three missing precision flags nor the /start readiness fix — the fixture failures and the
readiness race are unchanged. The one behavioural change in range is
#390, which increases the simulated downtime,
and that is exactly the timing the @stale and @unavailable scenarios depend on.

The tallies below have been re-measured on v3.10.1 and are unchanged — same counts, same
failures by name. That is the expected result given the above: nothing in range touches what these
suites assert.

Deliberately not the testbed's own Compose file: that one bind-mounts a flags directory the
launchpad writes into, names its service flagd, and runs an envoy sidecar only the flagd e2e suites
need.

Running it, and the tally

mvn -pl tools/tck -am -DskipTests install     # once
mvn -Ptck -pl providers/ofrep test

A clean run is 65 scenarios: 46 pass, 17 skip, 2 fail — confirmed by measurement, and worth
recording how, because an earlier pass reported three failures reproducibly and suspected a
regression. Three consecutive runs gave 3, then 2, then 28. The tell is that the extra failure
moves — Example #3.3, then Example #2.1, then thirteen rows at once — always as
expected: TYPE_MISMATCH but was: FLAG_NOT_FOUND on flags the testbed certainly serves. That is
flagd-testbed#394's readiness race, not this
provider: POST /start returns before the seeded flags are evaluable. A real defect fails the same
row every time. Read a red run against the two-failure floor before attributing anything here. Both failures are the large-integer-flag
fixture gap that flagd-testbed#392 fills —
the mandatory precision scenario and the max-int32 @variants row — not provider defects, and
neither gets a deviation entry.

Worth filing against the Java OFREP provider

1. No initialize() means a misconfigured provider reports READY. Point it at a bogus baseUrl
   and every evaluation silently returns the code default with GENERAL, while the client status says
   everything is fine. One round trip in initialize() would fix it and unlock both @unavailable
   scenarios.
2. A value-less success is reported as FLAG_NOT_FOUND — the codeDefaultFlag gap above. This is
   the one with a filed deviation against it.
3. Not an EventProvider. OFREP's bulk-evaluation endpoint with ETag support is designed for
   exactly this; polling it would unlock @events, @stale and @configuration-change.
4. ParseError escapes the provider's own error mapping. Resolver.resolve catches only
   GeneralError, but OfrepApi throws ParseError on JsonProcessingException, and the two are
   siblings under OpenFeatureError. The SDK's blanket catch means an application still gets details
   rather than a throw, so the suite does not catch this — but the provider reports PARSE_ERROR where
   its own design intends GENERAL.
5. Rate-limit backoff is provider-global and cross-flag. A single 429 on one flag sets
   nextAllowedRequestTime, after which every flag's evaluation throws GeneralError until the
   deadline — including flags that were never rate-limited.
6. Latent, not currently reachable: OfrepResponse.getMetadata() calls ImmutableMap.copyOf on a
   field that stays null when the JSON omits metadata. Every live path launders the object through
   Resolution, whose constructor reads the field directly, so it is safe today — but a direct use of
   a deserialised OfrepResponse would NPE.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}