Pending in response for nested defers

[robrichard]

Given the following example:

query ExampleA {
  me{
    ... @defer(label: "Outer") {
      fieldForOuter
      ... @defer(label: "Inner") {
        fieldForInner
      }
    }
  }
}

In #80 we decided that the defer with label "Inner" must not be sent before the defer with the label "Outer". This discussion is to decide how the associated "pending" fields may be sent.

Is this a valid response?

Response Example 1

[
  {
    "data": {
      "me": {}
    },
    "pending": [
      { "path": ["me"], "id": "0", "label": "Outer" },
      // Pending for "Inner" is sent before "Outer" is complete
      { "path": ["me"], "id": "1", "label": "Inner" }
    ],
    "hasNext": true
  },
  {
    "incremental": [
      { "id": "0", "data": { "fieldForOuter": "foo" } },
      { "id": "1", "data": { "fieldForInner": "bar" } }
    ],
    "completed": [{ "id": "0" }, { "id": "1" }],
    "hasNext": false
  }
]

Alternatively, is this also a valid response?

Response Example 2

[
  {
    "data": {
      "me": {}
    },
    "pending": [
      { "path": ["me"], "id": "0", "label": "Outer" }
    ],
    "hasNext": true
  },
  {
    "pending": [
      // Pending for "Inner" is sent in the same response where it is completed
      { "path": ["me"], "id": "1", "label": "Inner" }
    ],
    "incremental": [
      { "id": "0", "data": { "fieldForOuter": "foo" } },
      { "id": "1", "data": { "fieldForInner": "bar" } }
    ],
    "completed": [{ "id": "0" }, { "id": "1" }],
    "hasNext": false
  }
]

I think that even though the defer with label "Inner" must be sent after the defer with the label "Outer", we should either allow the "pending" to be sent earlier, or sent in the same response where the defer is completed. If those are not allowed, the server must split the response into multiple payloads, which could cause unnecessary client re-renders.

Response Example 3

[
  {
    "data": {
      "me": {}
    },
    "pending": [
      { "path": ["me"], "id": "0", "label": "Outer" }
    ],
    "hasNext": true
  },
  {
    "pending": [
      { "path": ["me"], "id": "1", "label": "Inner" }
    ],
    "incremental": [
      { "id": "0", "data": { "fieldForOuter": "foo" } },
    ],
    "completed": [{ "id": "0" }],
    "hasNext": true
  },
  // Additional response causes an additional client re-render
  {
    "incremental": [
      { "id": "1", "data": { "fieldForInner": "bar" } }
    ],
    "completed": [{ "id": "1" }],
    "hasNext": false
  }
]

[robrichard]

Since we will rely on the absence of a "pending" object to indicate that a defer has been inlined. I think it will be important for clients that we send the "pending" object in the same response that contains the data that the pending path points to. Otherwise, how can a client know how long it needs to wait to determine if a defer is being executed or has been inlined? This would make Response 1 in the original post the only valid response.

@BoD @mjmahone any thoughts?

[BoD]

Thanks for flagging @robrichard! I'm not 100% sure at this point but - if the client code makes sure to accumulate the pending in each response and remove them when they're in completed, and use that to decide whether to read the related fields or not, then I believe these 3 options would work equally.

Example 2 is a bit odd of course since it has in the same response both a pending and completed for id 1 - but I think it would work.

Pinging @alessbell too

[robrichard]

I'm thinking about an example like this:

query ExampleB {
  me{
    ... @defer(label: "Outer") {
      fieldForOuter
      ... @defer(label: "Inner") {
        ... on SomeConcreteType {
          fieldForInner
      }
      }
    }
  }
}

If you receive this first response:

{
  "data": {
    "me": {}
  },
  "pending": [
    { "path": ["me"], "id": "0", "label": "Outer" }
  ],
  "hasNext": true
}

At this point you don't know if @defer(label: "Inner") {...} is going to be deferred or inlined. Maybe it doesn't matter because the data for @defer(label: "Outer") hasn't been sent yet, but I'm not sure if clients will have enough knowledge of the query to account for that.

[BoD]

Speaking for Apollo Kotlin only, the generated deserializers work fragment by fragment, so in this example the decision to read the inner fragment or not doesn't arise until we're reading the outer fragment. Because of that, it's ok if we get the pending for it later (in the same response we get the fields for outer).

But it's true we can't assume all clients will have this behavior, in that case, it would be safer to have all the pending ASAP (response example 1).

[benjie]

If the client knows Inner exists then it seems like it would also know Outer exists and that Inner is inside Outer. A client who doesn't know these things simply should not read from a path whilst there are any pending left for that path. I do not think that we should recurse in the algorithm to let clients know this early, I think that would put an undue performance burden on the server.