Implement ＠defer "June 2023" response format #6331

BoD · 2024-12-17T15:20:02Z

Implements the latest (as of 2025-09-24) ＠defer incremental response format as seen in examples and spec edits.

A protocol can now be passed to the HttpNetworkTransport to choose which to use (legacy 20220824 is still the default).

svc-apollo-docs · 2024-12-17T15:20:06Z

✅ Docs Preview Ready

Configuration

{
  "repoOverrides": {
    "apollographql/apollo-kotlin@main": {
      "remote": {
        "owner": "apollographql",
        "repo": "apollo-kotlin",
        "branch": "defer-incremental-response-format-june-2023"
      }
    }
  }
}

Name	Link
Commit	`e2da859`
Preview	https://www.apollographql.com/docs/deploy-preview/1919dfd3b4a18c13cba2
Build ID	1919dfd3b4a18c13cba2
File Changes	0 new, 1 changed, 0 removed `* (developer-tools)/kotlin/(latest)/caching/declarative-ids.mdx`
Pages	1

1 pages published. Build will be available for 30 days.

apollo-librarian · 2025-07-17T09:39:26Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* (developer-tools)/kotlin/v5/index.mdx

Build ID: 65212b0a9c9b1f3e8aaf6e6a
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/65212b0a9c9b1f3e8aaf6e6a

martinbonnin · 2025-08-21T14:17:05Z

Apollo Client 4 introduces different handlers for different incremental formats. We could do the same while the format iterates.

…count.

…gmentIdentifier -> IncrementalResultIdentifier

… configuration. Defaults to the legacy one.

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt

.github/workflows/defer-integration-tests.yml

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt

libraries/apollo-api/api/apollo-api.api

...otlin/com/apollographql/apollo/internal/incremental/Defer20220824IncrementalResultsMerger.kt

.../commonMain/kotlin/com/apollographql/apollo/internal/incremental/IncrementalResultsMerger.kt

libraries/apollo-runtime/api/android/apollo-runtime.api

martinbonnin · 2025-09-25T09:42:04Z

...-runtime/src/commonMain/kotlin/com/apollographql/apollo/network/http/HttpNetworkTransport.kt

      this.engine = httpEngine
    }

+    fun incrementalDeliveryProtocol(incrementalDeliveryProtocol: IncrementalDeliveryProtocol) = apply {


Missing KDoc here

Also, looks like apollo-client went with incrementalHandler. Might be worth reusing some of the terminology? But we also have "protocol" for other things like WebSockets so my logaf is low.

martinbonnin · 2025-09-25T09:45:03Z

libraries/apollo-runtime/api/android/apollo-runtime.api

+public final class com/apollographql/apollo/internal/incremental/Defer20220824IncrementalResultsMerger : com/apollographql/apollo/internal/incremental/IncrementalResultsMerger {
+	public fun <init> ()V
+	public fun getHasNext ()Z
+	public fun getIncrementalResultIdentifiers ()Ljava/util/Set;
+	public fun getMerged ()Ljava/util/Map;
+	public fun isEmptyResponse ()Z
+	public fun merge (Ljava/util/Map;)Ljava/util/Map;
+	public fun merge (Lokio/BufferedSource;)Ljava/util/Map;
+	public fun reset ()V
+}
+
+public final class com/apollographql/apollo/internal/incremental/GraphQL17Alpha9IncrementalResultsMerger : com/apollographql/apollo/internal/incremental/IncrementalResultsMerger {


It's a bit weird that one is Defer20220824 and the other GraphQL17Alpha9. I haven't followed all the latest discussions lately but could we somwhat uniformized that? Are there specs versions (or tags) somewhere that describe what each one is doing?

It doesn’t look like there are any tags on the spec itself, so using graphql-js versions is cool. So maybe we should rename Defer20220824 to whatever version of graphql-js it corresponds to, for consistency. For now I kept the same naming as Apollo Client, but maybe it’s not too late to change the name there too.

Sounds good. Let's keep a practical approach here and do whatever is easiest. This is all experimental so the whole point is to move fast and iterate 👍

...-runtime/src/commonMain/kotlin/com/apollographql/apollo/network/http/HttpNetworkTransport.kt

BoD · 2025-09-25T13:37:25Z

...Main/kotlin/com/apollographql/apollo/internal/incremental/IncrementalDeliveryProtocolImpl.kt

+   * Both `@defer` and `@stream` are supported with this format.
+   */
+  object GraphQL17Alpha9 : IncrementalDeliveryProtocolImpl {
+    // TODO To be agreed upon with the router and other clients


We need to agree on that.
See also https://github.com/apollographql/apollo-client/pull/12926/files#r2369415433

...-runtime/src/commonMain/kotlin/com/apollographql/apollo/network/http/HttpNetworkTransport.kt

libraries/apollo-api/api/apollo-api.api

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt

...Main/kotlin/com/apollographql/apollo/internal/incremental/IncrementalDeliveryProtocolImpl.kt

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo/api/Executables.kt

martinbonnin · 2025-09-25T18:31:46Z

...-runtime/src/commonMain/kotlin/com/apollographql/apollo/network/http/HttpNetworkTransport.kt

              payloadResponse != null -> payloadResponse
              else -> null
            }
          } else {


Is there a way to test from the response whether it supports the incremental delivey protocol? Is there something in response.headers["content-type"] that signals what protocol was used by the server?

...rc/commonMain/kotlin/com/apollographql/apollo/network/websocket/WebSocketNetworkTransport.kt

...ollo-runtime/src/commonTest/kotlin/test/defer/GraphQL17Alpha9IncrementalResultsMergerTest.kt

BoD · 2025-09-26T13:36:30Z

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt

+      if (get("accept") == null) {
+        add(
+            HttpHeader("accept",
+                if (apolloRequest.operation is Subscription<*>) {
+                  "multipart/mixed;subscriptionSpec=1.0, application/graphql-response+json, application/json"
+                } else {
+                  "multipart/mixed;deferSpec=20220824, application/graphql-response+json, application/json"
+                }
+            )


I’ve kept this here because if somebody is using DefaultHttpRequestComposer but not HttpNetworkTransport it’s a behavior change (no accept header) - no strong opinion though.

What about application/graphql-response+json, application/json as a fallback? This is the most standard accept header. This way DefaultHttpRequestComposer is isolated from the incremental delivery concerns. That's a behavior change but probably very small blast radius?

Works for me 👍

…efaultHttpRequestComposer

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt

BoD force-pushed the defer-incremental-response-format-june-2023 branch from e2da859 to bb504f6 Compare July 17, 2025 09:39

BoD force-pushed the defer-incremental-response-format-june-2023 branch 2 times, most recently from e1ee642 to 4fa99ad Compare July 18, 2025 17:01

BoD added 9 commits September 22, 2025 12:10

Update DeferredJsonMerger to take pending and completed into ac…

6bfd599

…count.

Track pending fragment ids rather than completed ones.

26d6484

Update more tests

7963536

Add Apollo Server end-to-end tests

9ed0310

Add a few more edge case tests

0ed9a3e

Fix missed test

3527e1c

Support appending lists in DeferredJsonMerger (for @stream)

4310869

Rename DeferredJsonMerger -> IncrementalResultsMerger and DeferredFra…

a00106d

…gmentIdentifier -> IncrementalResultIdentifier

Fix running tests hardcoded to true

f05a860

BoD force-pushed the defer-incremental-response-format-june-2023 branch 2 times, most recently from 95e0b8c to fc4f174 Compare September 24, 2025 16:15

Support both legacy and modern incremental delivery protocols, with a…

8dfc4b3

… configuration. Defaults to the legacy one.

BoD force-pushed the defer-incremental-response-format-june-2023 branch from fc4f174 to 8dfc4b3 Compare September 24, 2025 16:23

BoD commented Sep 24, 2025

View reviewed changes

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt Outdated Show resolved Hide resolved

BoD marked this pull request as ready for review September 25, 2025 07:44

BoD requested a review from martinbonnin as a code owner September 25, 2025 07:44

martinbonnin reviewed Sep 25, 2025

View reviewed changes

.github/workflows/defer-integration-tests.yml Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

.github/workflows/defer-integration-tests.yml Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

libraries/apollo-api/api/apollo-api.api Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...otlin/com/apollographql/apollo/internal/incremental/Defer20220824IncrementalResultsMerger.kt Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

.../commonMain/kotlin/com/apollographql/apollo/internal/incremental/IncrementalResultsMerger.kt Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

libraries/apollo-runtime/api/android/apollo-runtime.api Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...-runtime/src/commonMain/kotlin/com/apollographql/apollo/network/http/HttpNetworkTransport.kt Outdated Show resolved Hide resolved

BoD added 3 commits September 25, 2025 11:48

Simplify CI job

e958e52

Do not expose accept headers in DefaultHttpRequestComposer's public API

986965c

Make more symbols internal

da34cd5

BoD commented Sep 25, 2025

View reviewed changes

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...-runtime/src/commonMain/kotlin/com/apollographql/apollo/network/http/HttpNetworkTransport.kt Outdated Show resolved Hide resolved

BoD added 2 commits September 25, 2025 15:43

Mark IncrementalDeliveryProtocol @ApolloExperimental

dc973f5

Rename Defer20220824 protocol to GraphQL17Alpha2 fpr consistency

a4d459c

martinbonnin reviewed Sep 25, 2025

View reviewed changes

libraries/apollo-api/api/apollo-api.api Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

libraries/apollo-api/api/apollo-api.api Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...Main/kotlin/com/apollographql/apollo/internal/incremental/IncrementalDeliveryProtocolImpl.kt Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo/api/Executables.kt Outdated Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...rc/commonMain/kotlin/com/apollographql/apollo/network/websocket/WebSocketNetworkTransport.kt Show resolved Hide resolved

martinbonnin reviewed Sep 25, 2025

View reviewed changes

...ollo-runtime/src/commonTest/kotlin/test/defer/GraphQL17Alpha9IncrementalResultsMergerTest.kt Show resolved Hide resolved

BoD added 5 commits September 26, 2025 10:08

Keep symbols public but deprecated

fa96da1

Let HttpNetworkTransport handle the Accept header

c4f2279

Rename Defer20220824 protocol to GraphQL17Alpha2 for consistency

658187d

Revert typealiases and use DeferredFragmentIdentifier again

9b6387e

Revert handling incremental results in WebSocket

8bd38c6

BoD commented Sep 26, 2025

View reviewed changes

Default to application/graphql-response+json, application/json in D…

7474fb1

…efaultHttpRequestComposer

martinbonnin reviewed Sep 26, 2025

View reviewed changes

...lo-api/src/commonMain/kotlin/com/apollographql/apollo/api/http/DefaultHttpRequestComposer.kt Show resolved Hide resolved

Implement ＠defer "June 2023" response format #6331

Are you sure you want to change the base?

Implement ＠defer "June 2023" response format #6331

Uh oh!

Conversation

BoD commented Dec 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

svc-apollo-docs commented Dec 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs Preview Ready

Uh oh!

apollo-librarian bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

martinbonnin commented Aug 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

BoD commented Dec 17, 2024 •

edited

Loading

svc-apollo-docs commented Dec 17, 2024 •

edited

Loading

apollo-librarian bot commented Jul 17, 2025 •

edited

Loading