Skip to content

Commit ff829e8

Browse files
authored
Merge pull request #950 from graphql-java-kickstart/agent-friendly-p9-resolver-pins
Pin resolver behaviour for methods, properties and Maps
2 parents 27337f0 + b70f073 commit ff829e8

8 files changed

Lines changed: 723 additions & 89 deletions

File tree

‎.claude/skills/verify-return-value-unwrapping/SKILL.md‎

Lines changed: 57 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
---
22
name: verify-return-value-unwrapping
3-
description: Exhaustively check, up to a bound, that a resolver method's return value reaches graphql-java fully unwrapped. Futures are awaited, generic wrappers are transformed, Optional and DataFetcherResult are handled, and list order, nulls and failures are kept, for every return type nested up to 3 containers deep. Use it before pushing any change to ReturnValueUnwrapper, TypeClassMatcher's unwrapping, GenericTypeResolver.resolve, the data fetchers in MethodFieldResolver, or the GenericWrapper defaults, and whenever a bug report says graphql-java got a CompletableFuture, Optional or wrapper object as a field value.
3+
description: Exhaustively check, up to a bound, that the value of a resolver method, public field or typed Map reaches graphql-java fully unwrapped. Futures are awaited, generic wrappers are transformed, Optional and DataFetcherResult are handled, and list order, nulls and failures are kept, for every return type nested up to 3 containers deep. Use it before pushing any change to ReturnValueUnwrapper, TypeClassMatcher's unwrapping, GenericTypeResolver.resolve, the data fetchers in MethodFieldResolver, PropertyFieldResolver or MapFieldResolver, or the GenericWrapper defaults, and whenever a bug report says graphql-java got a CompletableFuture, Optional or wrapper object as a field value.
44
---
55

66
# Verify return value unwrapping
77

88
## The property
99

10-
A user writes a resolver method whose return type nests containers, such as
11-
`CompletableFuture<List<Try<Payload>>>`. If the schema build accepts that method, then graphql-java must get
12-
exactly the value the method returned, with every container removed. Futures are waited on and generic wrappers go
10+
A user writes a resolver method, a public field or a `Map` whose type nests containers, such as
11+
`CompletableFuture<List<Try<Payload>>>`. If the schema build accepts it, then graphql-java must get
12+
exactly the value it returned, with every container removed. Futures are waited on and generic wrappers go
1313
through their transformers. List order and nulls are kept. A failed future or a throwing transformer fails the field.
1414
A `Future` that isn't a `CompletionStage` fails the field with the "can't wait on" error.
1515

@@ -36,18 +36,27 @@ The leaf is `Payload` (an object type), `String`, or `Object` for a union `Item
3636
implements `Future`, so only the declared type tells a leaf from a future. Each return type runs with an all-nullable
3737
and an all-non-null GraphQL type.
3838

39-
For each combination the check compiles a Java resolver class with that return type at runtime. It builds the schema
40-
through the public `SchemaParser` API, which rejects about a quarter of the combinations, such as `Optional` below the top
41-
level. For every accepted one it executes the query once for each value that makes at most `--budget` (default 2)
42-
non-default choices. When the return type holds futures, it runs each value three ways: futures already completed,
39+
Each return type runs as three kinds of resolver, each compiled as a Java class at runtime:
40+
41+
| Kind | Generated resolver | Data fetcher |
42+
|---|---|---|
43+
| `method` | `public <type> field()` on the query resolver | `MethodFieldResolver` |
44+
| `property` | `public <type> field;` on the query resolver, which is also what a Kotlin `@JvmField` compiles to | `PropertyFieldResolver` |
45+
| `map` | `extends HashMap<String, <type>>`, bound to `type Holder` and returned by `Query.holder` | `MapFieldResolver` |
46+
47+
The check builds each schema through the public `SchemaParser` API, which rejects about a fifth of the combinations, such as
48+
`Optional` below the top level. For every accepted one it executes the query once for each value that makes at most
49+
`--budget` (default 2) non-default choices. Properties and Maps use `--property-budget` (default 1), only the nullable
50+
GraphQL type and only the first-created-first completion order, because what they add is how the value is read, and the
51+
methods already cover the rest. When the return type holds futures, it runs each value three ways: futures already completed,
4352
and pending futures completed after the data fetcher returns, first-created first and last-created first.
4453

4554
The expected result is what graphql-java returns when a plain data fetcher on the same schema returns the plain value,
4655
or throws the failure. So graphql-java's own null handling and error format apply to both sides. When one value
4756
holds several failures, any one of them failing the field counts as correct.
4857

4958
`ReturnValueUnwrappingTest` compiles `Check.java` and `Fixtures.java` at test time and runs the check, so `mvn verify`
50-
runs it at the default bounds on every build. About 172,000 executions run in about 15 seconds.
59+
runs it at the default bounds on every build. About 226,000 executions run in about 18 seconds on JDK 17.
5160

5261
## Run
5362

@@ -63,13 +72,14 @@ as `-Dunwrapping.args`, and prints the report. On a failure it also prints the p
6372
| Exit | Meaning |
6473
|---|---|
6574
| 0 | `PASS`, or `PASS apart from the known findings above` |
66-
| 1 | `FAIL`: a return type that isn't a known finding breaks the property |
75+
| 1 | `FAIL`: a return type that isn't a known finding breaks the property. `NEW`: a known finding matches more accepted return types than its line records |
6776
| 2 | `MODEL ERROR`: the checkout or the check didn't compile, or the build rejected a return type the check must exercise, so a pass would prove nothing |
68-
| 3 | `STALE`: a known finding no longer fails. Delete its line from `known-findings.txt` |
77+
| 3 | `STALE`: a known finding matches a return type that no longer fails, or fewer accepted return types than its line records |
6978

70-
Options: `--depth N`, `--budget N`, `--show N` (counterexamples printed, default 15), and `--rejected`, which lists
79+
Options: `--depth N`, `--budget N`, `--property-budget N`, `--show N` (counterexamples and stale return types printed, default 15), and `--rejected`, which lists
7180
every combination the schema build rejected, with the build's error. A depth below 3 can't build the `mustAccept`
72-
return types, so it ends in `MODEL ERROR`.
81+
return types, so it ends in `MODEL ERROR`. `NEW` and `STALE` apply only at the default depth and budgets, because the
82+
counts in `known-findings.txt` are for those.
7383

7484
## Reading a counterexample
7585

@@ -81,7 +91,8 @@ public List<Future<Payload>> field() for field: [Payload] (21 failing execut
8191
got: {errors=[{message=Exception while fetching data (/field[1]/data) : Expected source object to be an instance of 'unwrapcheck.Fixtures$Payload' but instead got 'java.util.concurrent.FutureTask', ...
8292
```
8393

84-
The first line is the resolver method and the field's GraphQL type. `returns` is the value the method returned.
94+
The first line is the resolver and the field's GraphQL type. A property prints as `public List<Future<Payload>> field;`
95+
and a Map as `extends HashMap<String, List<Future<Payload>>> for Holder.field: [Payload]`. `returns` is the value the method returned.
8596
`Later(CompletableFuture(x))` means a `Later` whose transformer returns a `CompletableFuture` of `x`. Only the first
8697
failing value per return type is shown. Rerun with a higher `--show` to see more return types.
8798

@@ -96,24 +107,39 @@ A real bug versus a modeling error:
96107
- **Modeling error.** The check's own idea of the value is wrong. For example, a new container variant builds a value
97108
that its declared type doesn't allow, or the error message the check expects for a `FutureTask` (in `build`, case
98109
`FUTURE_TASK`) differs from a message the library changed on purpose. Confirm against the library's own tests in
99-
`src/test/kotlin/graphql/kickstart/tools/NestedGenericWrapperTest.kt` before you edit the check.
110+
`src/test/kotlin/graphql/kickstart/tools/NestedGenericWrapperTest.kt` before you edit the check. Properties and Maps
111+
are expected to fail a `FutureTask` with the method's wording, naming the generated class and `field`.
100112
- **`MODEL ERROR` about rejected return types.** A change made the build reject a return type in `mustAccept` in
101113
`Check.java`. That's either a regression in the build, which you report, or an intended change, after which you swap in
102114
another accepted return type of the same kind.
103115

104116
## Known findings
105117

106118
`src/test/resources/returnvalue/known-findings.txt` lists the return types that break the property at the sync commit, one per line as
107-
`<regex over the return type as the check prints it> # <what goes wrong>`. They still
108-
print as `KNOWN` with a counterexample on every run, and the check passes apart from them. A new break inside a known
109-
pattern is hidden, so after a change to the code a known finding covers, read its counterexample.
110-
111-
At the sync commit there are none. The check found two bugs when it was written, and both are fixed. One was a
112-
`DataFetcherResult` inside an `Optional` (#939). The other was a wrapper whose transformer returns a future, directly around
113-
a declared future (#938). A `withTransformer` registration keeps that #938 behavior, which is why `Later` is registered
114-
through `withCompletionStageTransformer`.
115-
116-
When a fix lands, the check exits 3. Delete the line then, so that a regression shows up as `FAIL`.
119+
`<count> <regex> # <what goes wrong>`. The regex is matched against the kind and the short return type, such as
120+
`property List<CompletableFuture<String>>`, so a pattern without a kind covers all three. The first matching line wins.
121+
Matching return types still print as `KNOWN` with a counterexample on every run, and the check passes apart from them.
122+
123+
Each line must match only return types that fail, and exactly `<count>` of the return types the build accepts. A
124+
matched return type that passes makes the check `STALE` and names it, so a partial fix has to narrow the line, and a later
125+
regression in a fixed return type is a `FAIL`. A count that grows makes it `NEW`, because a return type the build used to
126+
reject now fails under the line. What stays hidden is a known return type that starts failing in a different way, so
127+
after a change to the code a known finding covers, read its counterexample.
128+
129+
At the sync commit, methods have none. Properties and Maps hand their value to graphql-java as it is. graphql-java awaits
130+
only a top-level `CompletionStage`, reads a `DataFetcherResult` at the top, inside that future and as a list element, and
131+
unboxes any `Optional`, but not a `DataFetcherResult` inside one. So every nested future, every generic wrapper, a
132+
`DataFetcherResult` inside an `Optional`, and a `FutureTask` behind a declared `Future` fail for them. The five lines
133+
match exactly those 2,850 return types, and their counts add up to it. A String field gets the container's `toString`,
134+
such as `CompletableFuture@5a7cb161[Completed normally]`, with no error.
135+
136+
The check found two method bugs when it was written, and both are fixed. One was a `DataFetcherResult` inside an
137+
`Optional` (#939). The other was a wrapper whose transformer returns a future, directly around a declared future (#938). A
138+
`withTransformer` registration keeps that #938 behavior, which is why `Later` is registered through
139+
`withCompletionStageTransformer`.
140+
141+
When a fix lands, the check exits 3 and names the return types that pass. Narrow the line to the rest and set its count,
142+
or delete it when none fail, so that a regression shows up as `FAIL`.
117143

118144
## What this does not cover
119145

@@ -126,10 +152,12 @@ When a fix lands, the check exits 3. Delete the line then, so that a regression
126152
- Lists of more than 2 elements, more than 2 non-default choices per value, more than 3 containers, and completion
127153
orders other than the two listed. A pass says nothing beyond those bounds.
128154
- Which return types the schema build should reject. The check only exercises what the build accepts.
155+
- Untyped Maps, whose value type is `Object`, properties with a getter (those run as methods), and properties and Maps on
156+
a type below the root other than `Holder`. `ResolverCompatibilityTest` pins untyped Maps and Kotlin `@JvmField`s.
129157

130158
## Coverage and sync
131159

132-
Last confirmed to describe the code at commit `cd3233ca` (master, 2026-10-30). It covers:
160+
Last confirmed to describe the code at commit `af9ba4ad` (agent-friendly, 2026-11-04). It covers:
133161

134162
| File | What |
135163
|---|---|
@@ -138,11 +166,13 @@ Last confirmed to describe the code at commit `cd3233ca` (master, 2026-10-30). I
138166
| `src/main/kotlin/graphql/kickstart/tools/GenericTypeResolver.kt` | `resolve`, `resolveTypeVariables` |
139167
| `src/main/kotlin/graphql/kickstart/tools/resolver/MethodFieldResolver.kt` | `createDataFetcher` (`valueClass`, the unwrapper), `returnType`, `returnValueMatch`, `LightMethodFieldResolverDataFetcher` |
140168
| `src/main/kotlin/graphql/kickstart/tools/SchemaParserOptions.kt` | `GenericWrapper` and the default wrappers in `build()` |
169+
| `src/main/kotlin/graphql/kickstart/tools/resolver/PropertyFieldResolver.kt` | all of it |
170+
| `src/main/kotlin/graphql/kickstart/tools/resolver/MapFieldResolver.kt` | all of it, for Map subclasses with a typed value |
141171

142172
To see whether a change needs another look:
143173

144174
```bash
145-
git log --oneline cd3233ca..HEAD -- src/main/kotlin/graphql/kickstart/tools/resolver/ReturnValueUnwrapper.kt src/main/kotlin/graphql/kickstart/tools/TypeClassMatcher.kt src/main/kotlin/graphql/kickstart/tools/GenericTypeResolver.kt src/main/kotlin/graphql/kickstart/tools/resolver/MethodFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/SchemaParserOptions.kt
175+
git log --oneline af9ba4ad..HEAD -- src/main/kotlin/graphql/kickstart/tools/resolver/ReturnValueUnwrapper.kt src/main/kotlin/graphql/kickstart/tools/TypeClassMatcher.kt src/main/kotlin/graphql/kickstart/tools/GenericTypeResolver.kt src/main/kotlin/graphql/kickstart/tools/resolver/MethodFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/SchemaParserOptions.kt src/main/kotlin/graphql/kickstart/tools/resolver/PropertyFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/resolver/MapFieldResolver.kt
146176
```
147177

148178
Move the sync commit forward only after you've read those changes and confirmed that the containers, variants and

‎.claude/skills/verify-return-value-unwrapping/check.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ fi
1515

1616
sed -n '/AssertionError: /,/^\tat /p' "$log" | sed -e '1s/.*AssertionError: //' -e '$d'
1717
echo "Maven log: $log"
18-
grep -q '^FAIL:' "$log" && exit 1
18+
grep -q -E '^(FAIL|NEW):' "$log" && exit 1
1919
grep -q 'MODEL ERROR:' "$log" && exit 2
2020
grep -q '^STALE:' "$log" && exit 3
2121
tail -40 "$log"

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
9292
|---|---|
9393
| A resolver method's return value is unwrapped by one rule that the schema build and the data fetcher share | docs only |
9494
| A resolver method's parameter layout, type variables and source are decided once, at schema build | docs only |
95+
| A change to how resolvers are found, bound or unwrapped keeps what a method, a property and a Map field return | `ResolverCompatibilityTest` and the bounded check in `ReturnValueUnwrappingTest`. Each lists exactly today's property and Map gaps as known findings, and fails when one is fixed until it's removed, or when a new failure would hide under one |
9596
| One output has one builder. Don't add a second path that builds the same thing | docs only |
9697
| Read an SDL type's members merged with its extensions, never from the raw definition | docs only |
9798
| Reuse an existing structure before you add a parallel one | docs only |

‎src/test/kotlin/graphql/kickstart/tools/RawGenericFixtures.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package graphql.kickstart.tools;
22

33
import java.util.List;
4+
import java.util.Optional;
45
import java.util.concurrent.CompletableFuture;
56

67
// Raw types can't be expressed in Kotlin, so these fixtures must stay in Java.
@@ -14,6 +15,14 @@ public Tree tree() {
1415
}
1516
}
1617

18+
public static class RawOptionalResolver implements GraphQLQueryResolver {
19+
20+
@SuppressWarnings({"rawtypes", "unused"})
21+
public String raw(Optional value) {
22+
return String.valueOf(value);
23+
}
24+
}
25+
1726
public static class Tree<T> {
1827
private final T value;
1928

0 commit comments

Comments
 (0)