[jlouvel]

Closes #1588. Part of #1581.

Draft: depends on #1595 (streaming multipart, #1587). This branch is the G4 server branch (#1593) merged with feat/streaming-multipart, so the diff against #1593 also shows #1595's commit until it is merged. It does not depend on the WebSocket client (#1594).

Summary

@defer results over multipart/mixed, experimental and off by default on both sides. The GraphQL incremental delivery RFC is not finalized, and graphql-java 26.1 implements @defer only (Directives.DeferDirective); there is no @stream. Schemas must declare the directive.

server.setIncrementalDeliveryEnabled(true);

client.setIncrementalDeliveryEnabled(true);
ExecutionResult result = client.execute("{ fast ... @defer(label: \"d\") { slow } }", null, null);
if (result instanceof IncrementalExecutionResult incremental && incremental.hasNext()) {
    incremental.getIncrementalItemPublisher().subscribe(subscriber);   // DelayedIncrementalPartialResult
}

Server

• When a query or mutation accepts multipart/mixed, graphql-java's incremental support is enabled for that execution only (GraphQL.unusualConfiguration(input).incrementalSupport()). An IncrementalExecutionResult is streamed with MultipartStreamRepresentation: the initial result, then each DelayedIncrementalPartialResult, as application/json parts (boundary -, deferSpec=20220824, graphql-java's format).
• Delayed results are requested one at a time and bounded by maxQueuedBytes. A failure aborts the response rather than ending it cleanly, so that clients can't mistake a partial result for a complete one.
• Without multipart/mixed in Accept, or when disabled, @defer is executed inline as before. Results that are not incremental are plain JSON.

Client

• execute() also accepts multipart/mixed and returns graphql-java's own IncrementalExecutionResult, with incremental payloads rebuilt as DeferPayload / StreamPayload (data or items, path, label, errors, extensions).
• Its item publisher reads the following parts on demand from a virtual thread. It accepts a single subscriber, and the response is released on completion, failure or cancellation (cancel aborts the request). Parts are bounded by maxResponseBytes, and a truncated stream is a GraphqlTransportException.

GraphqlResultQueue (internal) now serializes any result type, so SSE, WebSocket and incremental delivery share the same back-pressure and byte accounting.

Validation

./mvnw -B verify -P default,test -pl org.restlet.ext.graphql (with core from this branch): 63 tests, 0 failures; 91.2% instruction coverage (gate 80%); Spotless, SpotBugs, Javadoc, -Werror and dependency convergence pass.

New GraphqlIncrementalTestCase (7 tests): wire format, with the initial part read while the deferred field is still blocked; inline execution without multipart/mixed or when disabled (406 when only multipart/mixed is acceptable); client publisher with DeferPayload data and label, single subscriber; deferred field errors as payload errors; plain results stay plain; cancellation and invalid demand; a server-side failure aborting the response and surfacing as a GraphqlTransportException.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Critical multipart handling flaws allow forged parts and can falsely signal successful stream termination after a writer failure.

6 open issues

• Leave multipart stream incomplete when writing a part fails · New
• Reject boundary tokens at the start of content · New
• Reject invalid demand without blocking on part reads · New
• Preserve null extension values when copying the map · New
• Verify the closing delimiter before signaling completion · New
• Close the reader on completion, failure, and cancellation · New

What changed in this PR

Adds experimental, opt-in GraphQL @defer delivery over multipart/mixed, building on streaming multipart support in Restlet core.

Changes:

• Adds a streaming multipart writer, bounded reader, and media-type constant.
• Integrates incremental responses into the GraphQL server and client, reusing shared result-queue accounting.
• Adds multipart and incremental-delivery tests and updates the changelog.

File	Description
org.restlet/​src/​test/​java/​org/​restlet/​representation/​MultipartStreamTestCase.java	Tests multipart framing, limits, validation, and streaming.
org.restlet/​src/​main/​java/​org/​restlet/​representation/​MultipartStreamRepresentation.java	Writes and flushes multipart parts as produced.
org.restlet/​src/​main/​java/​org/​restlet/​representation/​MultipartStreamReader.java	Reads streamed parts with size limits.
org.restlet/​src/​main/​java/​org/​restlet/​data/​MediaType.java	Adds MULTIPART_MIXED.
org.restlet.ext.graphql/​src/​test/​java/​org/​restlet/​ext/​graphql/​GraphqlIncrementalTestCase.java	Tests incremental delivery, fallback, cancellation, and failures.
org.restlet.ext.graphql/​src/​main/​java/​org/​restlet/​ext/​graphql/​internal/​GraphqlResultQueue.java	Supports serialization of additional result types.
org.restlet.ext.graphql/​src/​main/​java/​org/​restlet/​ext/​graphql/​internal/​GraphqlIncrementalStream.java	Streams initial and delayed GraphQL results.
org.restlet.ext.graphql/​src/​main/​java/​org/​restlet/​ext/​graphql/​GraphqlServerAdapter.java	Enables negotiated, opt-in incremental execution.
org.restlet.ext.graphql/​src/​main/​java/​org/​restlet/​ext/​graphql/​GraphqlIncrementalPublisher.java	Converts multipart responses into incremental results.
org.restlet.ext.graphql/​src/​main/​java/​org/​restlet/​ext/​graphql/​GraphqlClientAdapter.java	Adds opt-in multipart response handling.
changes.md	Documents multipart APIs and incremental GraphQL support.

_{Review effort: Balanced}

[sonarqubecloud]

Quality Gate passed

Issues
31 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud