Skip to main content

Alternative proposal for `@stream`/`@defer`

At a glance​

Timeline​

This RFC is an alternative solution to incremental delivery. This is a very early draft to enable sharing this solution with the incremental delivery working group, and, if ratified, may either be merged into @robrichard et al's excellent work in #742, or supersede it.

This PR currently only addresses the algorithms in the execution part of the specification (and is based off of a recent draft of the GraphQL specification, rather than any preceding work), so for accompanying specification text regarding the syntax and directives of incremental delivery, please see the excellent prior work in #742.

The goal of this proposal is to address the needs of incremental delivery whilst:

  1. Ensuring that the resolver at each path in the response is called at most once, to ensure that the individual payloads in an incremental delivery stream can always be reconciled into a final object that would be equivalent to the object that could be produced by removing all the @stream and @defer directives from the request.
  2. Ensuring that contents of a @defer'd or @stream'd selection set are sent atomically in a single event, such that MyFragment: __typename and other fragment identification approaches can be relied upon to confirm that the entire fragment is present.
  3. Avoiding duplicate delivery of leaves in order to reduce both network traffic, and memory load/redundant processing on client and server.
  4. Ensuring that you know if there is still pending data under a given path in the response.
  5. Allowing multiple streamed/deferred responses to be batched together into the same event to minimize client workload and reduce network traffic.

Non-goals of this proposal are:

  • Ensuring that you can check on the status of a specific @stream or @defer directives issued in the request.
    • There is generally not a one-to-one relationship between @stream/@defer directives in the request and any components in the response.
  • Allowing you to to set the priority of sibling @defers
    • There are no sibling defers, only nested defers
    • Currently ... @defer { ... @defer { a } } is equivalent to ... @defer { a }, but we might change this.

The significant change in this RFC is that it is built around the field merging algorithm that we already have, and allows merging @defers not just within a single selection set, but across the entire request. It works based on "defer layers" - thus for a query such as:

{
  a {
    b
    ... @defer { c { c1 } }
    d {
      e
      ... @defer { f }
    }
  }
  g
  ... @defer {
    a {
     c {
       ... @defer { c2 }
     }
    }
    h
  }
}

The first query to be resolved is as before:

{
  a {
    b
    d {
      e
    }
  }
  g
}

Yielding something like:

{
  data: {
    a: {
      b: "B",
      d: {
        e: "E"
      }
    },
    g: "G"
  },
  pending: [
    { id: 0, path: [] }
  ],
  hasNext: true
}

Next the first layer of @defer'd leaves is evaluated, which results in the following selection sets being evaluated at the following paths:

  • path: [], selection: { h }
  • path: ['a'], selection: { c { c1 } }
  • path: ['a', 'd'], selection: { f }

All three of these are evaluated (separately, in parallel) and then grouped together into the same event, something like:

{
  incremental: [
    { path: [], data: { h: "H" } },
    { path: ['a'], data: { c: { c1: "C1" } } },
    { path: ['a', 'd'], data: { f: "F" } }
  ],
  completed: [
    { id: 0 }
  ],
  pending: [
    { id: 1, path: ['a', 'c'] }
  ],
  hasNext: true
}

Finally we look at the next layer of @defer, which would yield:

  • path: ['a', 'c'], selection: { c2 }

Which would yield:

{
  incremental: [
    { path: ['a', 'c'], data: { c2: "C2" } }
  ],
  completed: [
    { id: 1 }
  ],
  hasNext: true
}

and finally:

{
  hasNext: false
}

(Note: we can probably optimize this to put the hasNext: false in the previous payload instead, but I've not yet tried to write that into the spec text.)