Reject futures that graphql-java can't wait on

[oryan-block]

Fixes #203

Checklist

• Pull requests follows the contribution guide
• New or modified functionality is covered by tests

Description

Stacked on #836, merge that first.

In #203 a resolver declared as Future<Organization> returns RxJava's Single#toFuture(), and its child fields fail with Expected source object to be an instance of '...Organization' but instead got 'io.reactivex.internal.observers.FutureSingleObserver'. The default GenericWrapper(Future::class, 0) is an identity transformer, so it only unwraps the type at scan time. At runtime graphql-java only waits on a CompletionStage, so any other Future became the field value:

• object fields fail on their children with a source type mismatch;
• list fields fail with type mismatch error, expected type LIST;
• scalar fields silently serialize the future's toString, e.g. java.util.concurrent.FutureTask@1b2c3d[Completed normally].

A suspend function that returns any future, CompletableFuture included, has the same problem, because graphql-java doesn't flatten a future that completes with another future.

Now the field fails with an error that says what to return instead:

• Resolver method 'Query.organization' resolved to a io.reactivex.internal.observers.FutureSingleObserver, which graphql-java can't wait on. Return a CompletionStage, such as a CompletableFuture, from the method or its generic wrapper transformer instead.
• Suspend function 'Query.organization' resolved to a java.util.concurrent.CompletableFuture, which graphql-java can't wait on. Return its value instead.

The future is never waited on, even if it's already done. Blocking the fetching thread would delay sibling fields, since graphql-java calls fetchers one at a time on that thread, and it would hang on a plain future that only completes after graphql-java dispatches DataLoaders. Reading only futures that are already done would make the result depend on timing: it would work in tests and fail under load.

The check runs after the generic wrapper transformer, so a transformer can still unwrap a plain future (GenericWrapper.withTransformer(FutureTask::class, 0, { it.get() })). A value is only rejected if it isn't an instance of the class the schema type was matched to at scan time. Because of that:

• a value that implements Future but is the schema type itself (fun job(): Job with class Job : Future<String>) still resolves;
• a Future that isn't unwrapped because useDefaultGenericWrappers(false) is set still resolves;
• a return type that's a type variable bound to Future is checked;
• a custom transformer that returns a plain future is checked. That's tfadsilva's comment on Help with Default Generic Wrappers #203: Flowable.toList().toFuture() in a transformer.
• a union field declared Future<Object> (or Future<Any>) is checked. Every value is an Object, so when the type unwraps to Object any future from a method declared to return Future is checked. On master a plain future there made graphql-java throw a TypeResolverError out of execute.

Not covered, same behaviour as master:

• a Java field or @JvmField typed Future<T>. Those go through PropertyFieldResolver, which doesn't apply generic wrapper transformers at all;
• Optional<Future<T>> and DataFetcherResult<Future<T>>, where the future is nested inside another container;
• Future<out R>, a wildcard over a class type variable;
• a declared FutureTask<String> or raw Future on a scalar field, which no wrapper unwraps.

Behaviour change, so this should go out in a minor release:

• Downstream workarounds now get the error. Anyone who worked around Help with Default Generic Wrappers #203 after the data fetcher, with a ValueUnboxer, an Instrumentation that wraps data fetchers, a SchemaDirectiveWiring, or a custom scalar Coercing that unwraps the future, now gets the error, because the data fetcher throws before their code sees the value. The fix is to move the unwrapping into a generic wrapper transformer, or return a CompletionStage.
• Nulls spread one level higher. The error is now on the field itself instead of its children. On a non-null field, the null spreads one level further up, so sibling data that used to come back can be lost.
• Suspend functions under a regular Job. For suspend functions, the error is thrown inside the coroutine like any other resolver exception. If the request's context is a CoroutineScope with a regular Job, sibling suspend fields are cancelled.
• The docs. The schema parser options docs list Future as a well-known wrapper without saying the runtime value has to be a CompletionStage. That needs a follow-up there.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud