fix(incremental): prevent lost or delayed successful shared results

[yaacovCR]

Follow-up to merged PR #4859.

Thanks to Duckki Oe (@duckki) for pointing out these issues and providing an initial fix.

That PR documented these bugs with skipped regression tests. This PR implements the successful-result fix and enables its regression tests. Additional integration tests cover delayed delivery and later owners.

Previously, we could skip a nested deferred fragment whose shared fields had succeeded before its parent finished. That was incorrect when the shared data had not yet been delivered. If the other fragment failed on a separate field, the data was lost; if its separate fields succeeded later, the data was delayed.

This PR announces the nested fragment and delivers its successful shared data when its parent completes. The data, including any shared stream, can therefore reach the client without waiting for the other fragment's separate fields.

@defer: another fragment fails on a separate field

{
  hero {
    ... @defer(label: "R") {
      nonNullName
      id
    }
    ... @defer(label: "P") {
      name
      ... @defer(label: "C") {
        id
      }
    }
  }
}

R and C share id, which returns 1. R fails because its own nonNullName returns null. After that error is sent, P's name resolves to "Luke".

Both versions start with:

{
  "data": {"hero": {}},
  "pending": [
    {"id": "0", "path": ["hero"], "label": "R"},
    {"id": "1", "path": ["hero"], "label": "P"}
  ],
  "hasNext": true
}

Then R fails:

{
  "hasNext": true,
  "completed": [
    {
      "id": "0",
      "errors": [
        {
          "message": "Cannot return null for non-nullable field Hero.nonNullName.",
          "locations": [
            {"line": 4, "column": 7}
          ],
          "path": ["hero", "nonNullName"]
        }
      ]
    }
  ]
}

Before this fix:

Previously, finishing P ended the response without announcing C or sending id, even though id had succeeded.

Response 3:

{
  "hasNext": false,
  "incremental": [
    {"id": "1", "data": {"name": "Luke"}}
  ],
  "completed": [
    {"id": "1"}
  ]
}

After this fix:

This commit announces C and delivers id when P finishes, so R's separate failure no longer loses C's data.

Response 3:

{
  "hasNext": false,
  "pending": [
    {"id": "2", "path": ["hero"], "label": "C"}
  ],
  "incremental": [
    {"id": "1", "data": {"name": "Luke"}},
    {"id": "2", "data": {"id": "1"}}
  ],
  "completed": [
    {"id": "1"},
    {"id": "2"}
  ]
}

@defer: another fragment's separate field is slower

{
  hero {
    ... @defer(label: "R") {
      nonNullName
      id
    }
    ... @defer(label: "P") {
      name
      ... @defer(label: "C") {
        id
      }
    }
  }
}

Here all three fields succeed. id returns 1 immediately. After the initial response, P's name resolves to "Luke". R's nonNullName stays pending until after P's response, then also resolves to "Luke".

Both versions start with:

{
  "data": {"hero": {}},
  "pending": [
    {"id": "0", "path": ["hero"], "label": "R"},
    {"id": "1", "path": ["hero"], "label": "P"}
  ],
  "hasNext": true
}

Before this fix:

Previously, P completed without announcing C. The shared id wasn't sent until R's separate nonNullName finished, unnecessarily delaying data that C was ready to deliver.

Response 2:

{
  "hasNext": true,
  "incremental": [
    {"id": "1", "data": {"name": "Luke"}}
  ],
  "completed": [
    {"id": "1"}
  ]
}

Response 3:

{
  "hasNext": false,
  "incremental": [
    {"id": "0", "data": {"nonNullName": "Luke"}},
    {"id": "0", "data": {"id": "1"}}
  ],
  "completed": [
    {"id": "0"}
  ]
}

After this fix:

This commit delivers id through C as soon as P finishes. R sends its separate field later.

Response 2:

{
  "hasNext": true,
  "pending": [
    {"id": "2", "path": ["hero"], "label": "C"}
  ],
  "incremental": [
    {"id": "1", "data": {"name": "Luke"}},
    {"id": "2", "data": {"id": "1"}}
  ],
  "completed": [
    {"id": "1"},
    {"id": "2"}
  ]
}

Response 3:

{
  "hasNext": false,
  "incremental": [
    {"id": "0", "data": {"nonNullName": "Luke"}}
  ],
  "completed": [
    {"id": "0"}
  ]
}

@stream: a separate field fails before the list is delivered

{
  nestedObject {
    ... @defer(label: "R") {
      nonNullScalarField
      ...Friends
    }
    ... @defer(label: "P") {
      scalarField
      ... @defer(label: "C") {
        ...Friends
      }
    }
  }
}
fragment Friends on NestedObject {
  nestedFriendList @stream(initialCount: 0) {
    name
  }
}

The shared nestedFriendList returns Luke, Han, and Leia immediately. R fails because its own nonNullScalarField returns null. After that error is sent, P's scalarField resolves to "parent".

Both versions start with:

{
  "data": {"nestedObject": {}},
  "pending": [
    {"id": "0", "path": ["nestedObject"], "label": "R"},
    {"id": "1", "path": ["nestedObject"], "label": "P"}
  ],
  "hasNext": true
}

Then R fails:

{
  "hasNext": true,
  "completed": [
    {
      "id": "0",
      "errors": [
        {
          "message": "Cannot return null for non-nullable field NestedObject.nonNullScalarField.",
          "locations": [
            {"line": 4, "column": 7}
          ],
          "path": ["nestedObject", "nonNullScalarField"]
        }
      ]
    }
  ]
}

Before this fix:

Previously, P completed and the response ended. C and the stream were never announced, so neither the empty list nor its items were sent.

Response 3:

{
  "hasNext": false,
  "incremental": [
    {"id": "1", "data": {"scalarField": "parent"}}
  ],
  "completed": [
    {"id": "1"}
  ]
}

After this fix:

This commit announces C and the stream with P's result. C sends the empty list, then the stream sends all three friends, so R's separate failure no longer loses the list.

Response 3:

{
  "hasNext": true,
  "pending": [
    {"id": "2", "path": ["nestedObject"], "label": "C"},
    {"id": "3", "path": ["nestedObject", "nestedFriendList"]}
  ],
  "incremental": [
    {"id": "1", "data": {"scalarField": "parent"}},
    {"id": "2", "data": {"nestedFriendList": []}}
  ],
  "completed": [
    {"id": "1"},
    {"id": "2"}
  ]
}

Response 4:

{
  "hasNext": false,
  "incremental": [
    {"id": "3", "items": [{"name": "Luke"}, {"name": "Han"}, {"name": "Leia"}]}
  ],
  "completed": [
    {"id": "3"}
  ]
}

Co-authored-by: Duckki Oe duckki.dev@gmail.com

[vercel]

@yaacovCR is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.