Spec edits for incremental delivery, Section 3 only

[robrichard]

Extracted from the full PR (#1110) and targeting an integration branch to aid in review.

Helpful reference material:

Response format examples: graphql/defer-stream-wg#69
Glossary: graphql/defer-stream-wg#106
GraphQL Conf talk: https://www.youtube.com/watch?v=LEyDeNoobT0

Response types

/** Currently defined types */
type RequestErrorResult = {
  errors: Error[] // request errors only
  extensions?: object
}
type ExecutionResult = {
  data: {} | null
  errors?: Error[] // execution errors only
  extensions?: object
}
type ResponseStream = ExecutionResult[]

/** New types that are yielded by an Incremental Stream */
interface InitialExecutionResult extends ExecutionResult {
  incremental: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type SubsequentExecutionResult = {
  incremental?: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type IncrementalStream = [InitialExecutionResult, ...SubsequentExecutionResult[]];

/** Response is updated to include IncrementalStream as a new member */
type Response = RequestErrorResult | ExecutionResult | ResponseStream | IncrementalStream;

type IncrementalResult = IncrementalObjectResult | IncrementalListResult

[benjie]

Lots of nit-picky comments but I think we're pretty close! Do we have a glossary somewhere? I think we need to be really crisp on terms like "result", "response", "payload" and the like.

[benjie]

I believe that we've refined the terminology around this: there's one response. The response for stream/defer is a stream consisting of an initial result payload followed by a number of incremental payloads. I couldn't find where we discussed this, so please correct as appropriate.

Suggested change

	responses: the initial response containing all non-deferred data, while
	subsequent responses include deferred data.
	payloads: the initial payload containing all non-deferred data, while subsequent
	payloads include deferred data.

[robrichard]

@benjie after the last discussion we had, I decided to drop payload. The response section now says:

The result of a GraphQL request must be either a single initial response or an
incremental stream. The response will be an incremental stream when the GraphQL
service has deferred or streamed data as a result of the @defer or @stream
directives. When the result of the GraphQL operation is an incremental stream,
the first value will be an initial response, followed by one or more subsequent
responses.

[benjie]

The "and" here implies this is an additional behaviour

Suggested change

	- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
	note below). When `false`, the field must not be streamed and all list items
	must be initially included. Defaults to `true` when omitted.
	- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
	note below). When `false`, the field must behave as if the `@stream` directive
	is not present—it must not be streamed and all of the list items must be
	included. Defaults to `true` when omitted.

[robrichard]

@benjie I added a rough glossary here: graphql/defer-stream-wg#106, I'll keep refining it as we go

[mjmahone]

These changes look correct to me, I don't think the definition of the @stream/@defer directives have changed in a very long time, so this feels good.

[benjie]

This is looking really good; all my suggestions are minor except the last one which I think warrants some extra work.

[benjie]

Terminology:

• initial execution result - confirms to execution result (just adds a couple more fields) 👍
• subsequent execution result - sounds like it should conform to execution result, but doesn't ({hasNext: false} very obviously fails this) 👎

If we continue with this naming, we should revisit the definition of execution result.

Did we already discuss changing to subsequent incremental execution result? To my ear the word incremental¹ makes it much clearer that the payload won't necessarily conform to execution result (a bit like "partial" - suddenly all the fields are no longer required).

Footnotes

1. You could think of each additional payload in a subscription as being a "subsequent execution result", but the term "incremental execution result" would not fit for subscriptions - it's clearly a different beast. ↩

[robrichard]

@benjie I decided to go with subsequent execution result instead of incremental execution result because we also need a name for the object in the incremental entry. As of the last discussion we are calling it an incremental result, (along with the other objects completed result, pending result).

The argument about subscriptions is compelling so I'm open to changing it, but I'm concerned having both an Incremental Execution Result and an Incremental Result will be confusing.

[benjie]

Suggested change

	...someFragment @defer(label: "someLabel", if: $shouldDefer)
	...someFragment @defer(if: $shouldDefer, label: "someLabel")

[benjie]

Suggested change

	@stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
	@stream(if: $shouldStream, label: "friendsStream", initialCount: 5) {

[benjie]

Minor, but we would expect this note to be in the same section. Having it under @stream's heading is unexpected without further signposting.

[benjie]

This feels like it warrants its own header, similar to Supporting Subscriptions at Scale (beautiful bit of alliteration there!), that can be referenced by both blocks.

Also, this feels like it should be normative. Putting "must" in a non-normative note feels wrong.

We should also be much clearer that this is on a case by case basis, so for example:

{
  list @stream {
    field1
    ...@defer {
      field2
    }
  }
}

In this case, different entries in the streamed list may or may not defer field2 - the @defer is not ignored "wholesale" but on an execution-position by execution-position basis.

Also, I think we should more strongly empower schema authors to opt out when they see fit, because there are many situations where streaming may add complexity without reducing latency for the client. For example: reverse cursor pagination...

query Things($cursor: String) {
  things(first: 1000, after: $cursor) {
    nodes @stream(initialCount: 2) { id name }
  }
}

^ for this, it can clearly stream from the datasource; however:

query ThingsReverse($cursor: String) {
  things(last: 1000, before: $cursor) {
    nodes @stream(initialCount: 2) { id name }
  }
}

^ in this case, you can't necessarily stream from the datasource, because the last record to come from the datasource (assuming you're fetching in reverse, discovering each next row as you go) is actually the first record you should return to the user.

Similarly:

query ThingsAwkward($cursor: String) {
  things(first: 1000, last: 100, after: $cursor) {
    nodes @stream(initialCount: 2) { id name }
  }
}

^ in this case we may not know which the last 100 will be until we've fetched them all. (This is of course a pathological query.)

Of course streaming the underlying data from your data source and streaming the result of the field's execution are two different things (and happen at different positions in the waterfall), so YMMV.