Skip to content

Proposal: update experimental defer support to the newer incremental delivery draft #4497

Open

Description

@duckki

I’d like to contribute an update to graphql-java’s experimental @defer support to align it with the newer incremental delivery specification draft. Before submitting PRs, I’d like to check whether there are existing plans or ongoing work in this area.

The working prototype is now public in duckki/graphql-java. I propose splitting the contribution into four PRs:

  1. Defer support only (branch, diff), behind an opt-in transition option. Preserve the current implementation, keep the new version mostly isolated, and include focused Spock tests for execution, errors, cancellation, DataLoader integration and compatibility.
  2. Optional differential testing against a Lean oracle (branch, diff), with deterministic input generation, saved regression cases, replay and shrinking.
  3. Stream support (branch, diff), including validation, backpressure and resource lifecycle tests.
  4. Expanded fuzzing (branch, diff), covering broader inputs, asynchronous scenarios and coverage profiles.

The branches are stacked in this order. Each linked diff isolates one stage; the first is based on 4c096208b, and each later diff is against the preceding branch.

The design follows a public Lean model with formal proofs of its documented properties. It includes two work-queue implementations:

The model provides a precise reference for execution semantics, while differential testing checks the Java implementation against that reference. My blog post, Formally Verified GraphQL Incremental Delivery, explains the verification work and its scope. The model and porting guide are supporting resources; each PR will explain its design and behavior directly in Java terms.

The first branch’s commits separate response types, collection/planning, scheduling/publication, and integration/compatibility tests. The contribution would add no new dependencies or HTTP transport. The prototype currently targets spec revision 045e193.

Are there existing plans this should coordinate with? Would this staged approach fit the project’s direction? Feedback on the opt-in transition and response API would help shape the first PR.

Activity

  1. andimarek commented on Oct 15, 2026

    @andimarek
    Member

    hey thanks a lot for that and that sounds great.

    One thing to note: I don't think we want to keep the current defer implementation around, but we would rather replace it with the updated spec: we will simply not maintain two defer implementations in GraphQL Java. If people really want or need the other version they will have to stay on the older version. cc @bbakerman

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions