defer/stream payloads in the initial response

[robrichard]

Context

In #41 the WG decided that defer/stream payloads will be sent inside of an incremental array. This incremental array can be sent in either the initial or subsequent payloads.

Example

Response 1:

{
  "data": {
    "hero": {
      "films": [{ "title": "A New Hope" }]
    }
  },
  "incremental":[{
    "label": "filmsStream",
    "path": ["hero", "films", 1],
    "items": [{"title": "The Empire Strikes Back"}]
  }],
  "hasNext": true
}

Response 2

{
  "incremental":[{
    "label": "filmsStream",
    "path": ["hero", "films", 2],
    "items": [{"title": "Return of the Jedi"}]
  }],
  "hasNext": false
}

Currently the spec PR includes the "incremental" entry when possible within the initial response:

• Initialize {initialIncremental} to an empty list.
• For each {record} in {initialRecords}:
  • Remove {record} from {subsequentPayloads}.
  • If {isCompletedIterator} on {record} is {true}:
    • Continue to the next record in {records}.
  • Let {payload} be the completed result returned by {dataExecution}.
  • Append {payload} to {initialIncremental}.
• If {initialIncremental} is not empty:
  • Add an entry to {initialResponse} named incremental containing the value
    {incremental}.
• Yield {initialResponse}.

With a naive server, including defer/stream payloads in the initial response could lead to worse performance than either ignoring the defer/stream or putting it in a later response. If there's a large amount of data that's ready synchronously, the entire payload could be slowed down during transport. But there could be good reasons to support it (maybe it makes sense for a caching proxy?).

[robrichard]

My current opinion is that the spec should allow defer/stream payloads in the initial response (and therefore clients must support parsing them), but with a note warning against pitfalls. The quoted section of the algorithm can be prefaced with an RFC2119 May/Optional. I think graphql-js shouldn't include defer/stream payloads in the initial response.

[yaacovCR]

Linking back to here, where I raised the request for clarification.

The above seems fine to me, thank you!

[yaacovCR]

Although I see a rough equivalence between advanced servers that are allowed/encouraged to not honor defer and inline the fields into the initial response and what we are talking about here in terms of sending available incremental payloads together with the initial response.

in fact, one could argue that the difference is only in how the payloads are “inlined” and that each format has its own benefits.

I am skeptical of inlining in general, so I don’t discount your view here. So bottom line I think we can use MAY as you say but we should also be careful within the spec to explicitly reference the rough equivalence and perhaps even enumerate some of the benefits of “true” inlining ie that there may be fewer duplicated fields and smaller payloads…