Skip to content

Commit ffacdf4

Browse files
robrichardrobrichard
committed
PR Feedback
1 parent b9d8e8a commit ffacdf4

File tree

2 files changed

+127
-106
lines changed

2 files changed

+127
-106
lines changed

‎spec/Appendix E -- Examples.md‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The _initial incremental stream result_ has:
3535
- a {"hasNext"} entry with the value {true}, indicating that the response is not
3636
yet complete.
3737

38-
If an error were to occur, it would also have an {"error"} entry; but not in
38+
If an error were to occur, it would also have an {"errors"} entry; but not in
3939
this example.
4040

4141
```json example
@@ -82,8 +82,8 @@ indicating that the deferred data has been completely delivered.
8282
The second _incremental stream update result_ contains the final stream results.
8383
In this example, the underlying iterator does not close synchronously so
8484
{"hasNext"} is set to {true}. If this iterator did close synchronously,
85-
{"hasNext"} would be set to {false} and this would be the final incremental
86-
stream update result.
85+
{"hasNext"} could be set to {false} and make this the final incremental stream
86+
update result.
8787

8888
```json example
8989
{
@@ -97,10 +97,9 @@ stream update result.
9797
}
9898
```
9999

100-
The third _incremental stream update result_ contains no incremental data.
101-
{"hasNext"} set to {false} indicates the end of the _incremental stream_. This
102-
incremental stream update result is sent when the underlying iterator of the
103-
`films` field closes.
100+
When the underlying iterator of the `films` field closes there is no more data
101+
to deliver, so the third and final _incremental stream update result_ sets
102+
{"hasNext"} to {false} to indicate the end of the _incremental stream_.
104103

105104
```json example
106105
{
@@ -163,13 +162,15 @@ In this example, the first _incremental stream update result_ contains the
163162
deferred data from `HomeWorldFragment`. There is one _completed result_,
164163
indicating that `HomeWorldFragment` has been completely delivered. Because the
165164
`homeWorld` field is present in two separate `@defer`s, it is separated into its
166-
own _incremental result_.
165+
own _incremental result_. In this example, this incremental result contains the
166+
id `"0"`, but since the `name` field was included in both `HomeWorldFragment`
167+
and `NameAndHomeWorldFragment`, an id of `"1"` would also be a valid response.
167168

168169
The second _incremental result_ in this _incremental stream update result_
169170
contains the data for the `terrain` field. This _incremental result_ contains a
170171
{"subPath"} entry to indicate to clients that the _response position_ of this
171-
result can be determined by concatenating the path from the _pending result_
172-
with id `"0"` and the value of this {"subPath"} entry.
172+
result can be determined by concatenating: the path from the _pending result_
173+
for id `"0"`, and the value of this {"subPath"} entry.
173174

174175
```json example
175176
{
@@ -196,6 +197,11 @@ delivered, clients are informed that the `NameAndHomeWorldFragment` has been
196197
completed by the presence of the associated _completed result_. Additionally,
197198
{"hasNext"} is set to {false} indicating the end of the _incremental stream_.
198199

200+
This example demonstrates that it is necessary for clients to process the entire
201+
incremental stream, as both the initial data and previous incremental results
202+
(with a potentially different value for {"id"}) may be required to complete a
203+
deferred fragment.
204+
199205
```json example
200206
{
201207
"incremental": [

‎spec/Section 7 -- Response.md‎

Lines changed: 111 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -89,32 +89,42 @@ yielded by an _incremental stream_.
8989

9090
An _initial incremental stream result_ must be a map.
9191

92-
The _initial incremental stream result_ must contain an entry with key {"data"},
93-
and may contain entries with keys {"errors"} and {"extensions"}. The value of
94-
these entries are defined in the same way as an _execution result_ as described
95-
in the "Data", "Errors", and "Extensions" sections below.
96-
97-
The _initial incremental stream result_ must contain an entry with the key
98-
{"hasNext"}. The value of this entry must be {true} if there are any
99-
_incremental stream update results_ in the _incremental stream_. The value of
100-
this entry must be {false} if the initial incremental stream result is the last
101-
response of the incremental stream.
102-
103-
The _initial incremental stream result_ must contain an entry with the key
104-
{"pending"}. The value of this entry must be a non-empty list of _pending
105-
result_. Each _pending result_ must be a map as described in the "Pending
106-
Result" section below.
92+
The _initial incremental stream result_ must contain entries with keys {"data"},
93+
{"pending"}, and {"hasNext"}, and may contain entries with keys {"errors"},
94+
{"incremental"}, {"completed"}, and {"extensions"}.
95+
96+
The value of {"data"}, {"errors"} and {"extensions"} are defined in the same way
97+
as an _execution result_ as described in the "Data", "Errors", and "Extensions"
98+
sections below.
99+
100+
The value of {"hasNext"} must be {false} if the initial incremental stream
101+
result is the last response of the incremental stream. Otherwise, {"hasNext"}
102+
must be {true}.
107103

108-
The _initial incremental stream result_ may contain an entry with they key
109-
{"incremental"}. The value of this entry must be a non-empty list of
104+
The value of {"pending"} must be a non-empty list of _pending result_. Each
105+
_pending result_ must be a map as described in the "Pending Result" section
106+
below.
107+
108+
The value of {"incremental"}, if present, must be a non-empty list of
110109
_incremental result_. Each _incremental result_ must be a map as described in
111110
the "Incremental Result" section below.
112111

113-
The _initial incremental stream result_ may contain an entry with they key
114-
{"completed"}. The value of this entry must be a non-empty list of _completed
112+
The value of {"completed"}, if present, must be a non-empty list of _completed
115113
result_. Each _completed result_ must be a map as described in the "Completed
116114
Result" section below.
117115

116+
Note: A GraphQL service is permitted to include incrementally delivered data in
117+
the _initial incremental stream_. For example, A GraphQL middleware layer, such
118+
as a caching CDN or proxy service, may wish to intercept and rewrite the
119+
_incremental stream_ before delivering it to a client. This service may collect
120+
some or all of the _pending result_, _incremental result_, and _completed
121+
result_ from the entire _incremental stream_ of the upstream service, and
122+
construct a new incremental stream containing a single payload: an _initial
123+
incremental stream result_ containing the all of the intercepted pending
124+
results, incremental results, and completed results, and the {"hasNext"} entry
125+
set to false. This would allow the client to efficiently render the entire
126+
result without having to process multiple payloads.
127+
118128
### Incremental Stream Update Result
119129

120130
:: An _incremental stream update result_ contains the result of executing any
@@ -125,23 +135,22 @@ must be incremental stream update results.
125135

126136
An _incremental stream update result_ must be a map.
127137

128-
Unlike the _initial incremental stream result_, an _incremental stream update
129-
result_ must not contain entries with keys {"data"} or {"errors"}.
138+
The _incremental stream update result_ must contain an entry with the key
139+
{"hasNext"}, and may contain entries with the keys {"pending"}, {"incremental"},
140+
{"completed"}, and {"extensions"}. Unlike the _initial incremental stream
141+
result_, an _incremental stream update result_ must not contain entries with
142+
keys {"data"} or {"errors"}.
130143

131-
An _incremental stream update result_ may contain an entry with the key
132-
{"extensions"}. The value of this entry is described in the "Extensions"
133-
section.
144+
The value of {"hasNext"} must be {true} for all but the last response in the
145+
_incremental stream_. Otherwise, {"hasNext"} must be {true}.
134146

135-
An _incremental stream update result_ must contain an entry with the key
136-
{"hasNext"}. The value of this entry must be {true} for all but the last
137-
response in the _incremental stream_. The value of this entry must be {false}
138-
for the last response of the incremental stream.
147+
The value of {"pending"}, {"incremental"}, and/or {"completed"}, if present are
148+
defined in the same way as an _initial incremental stream result_ as described
149+
in the "Pending Result", "Incremental Result", and "Completed Result" sections
150+
below.
139151

140-
The _incremental stream update result_ may contain entries with keys
141-
{"pending"}, {"incremental"}, and/or {"completed"}. The value of these entries
142-
are defined in the same way as an _initial incremental stream result_ as
143-
described in the "Pending Result", "Incremental Result", and "Completed Result"
144-
sections below.
152+
The value of {"extensions"}, if present, is defined in the same way as an
153+
_execution result_ as described in the "Extensions" section below.
145154

146155
### Response Position
147156

@@ -167,7 +176,7 @@ represents a path in the response, not in the request.
167176
When a _response path_ is present on an _error result_, it identifies the
168177
_response position_ which raised the error.
169178

170-
When a _response path_ is present on an _incremental result_, it identifies the
179+
When a _response path_ is present on a _pending result_, it identifies the
171180
_response position_ of the incremental data update.
172181

173182
A single field execution may result in multiple response positions. For example,
@@ -418,21 +427,23 @@ either the current response, or one of the following responses.
418427

419428
A _pending result_ must be a map.
420429

421-
Every _pending result_ must contain an entry with the key {"id"} with a string
422-
value. This {"id"} should be used by clients to correlate pending results with
423-
_incremental result_ and _completed result_. The {"id"} value must be unique for
424-
the entire _incremental stream_ response. There must not be any other pending
425-
result in the _incremental stream_ that contains the same {"id"}.
426-
427-
Every _pending result_ must contain an entry with the key {"path"}. When the
428-
pending result is associated with a `@stream` directive, it indicates the list
429-
at this _response position_ is not known to be complete. Clients should expect
430-
the GraphQL Service to incrementally deliver the remainder list items of this
431-
list. When the pending result is associated with a `@defer` directive, it
432-
indicates that the response fields contained in the deferred fragment are not
433-
known to be complete. Clients should expect the GraphQL Service to incrementally
434-
deliver the remainder of the fields contained in the deferred fragment at this
435-
_response position_.
430+
A _pending result_ must contain entries with the keys {"id"} and {"path"}, and
431+
may contain an entry with key {"label"}.
432+
433+
The value of {"id"} must be a string. This {"id"} should be used by clients to
434+
correlate pending results with _incremental result_ and _completed result_. The
435+
{"id"} value must be unique across the entire _incremental stream_ response.
436+
There must not be any other pending result in the _incremental stream_ with the
437+
same {"id"}.
438+
439+
The value of {"path"} must be a _response position_. When the pending result is
440+
associated with a `@stream` directive, it indicates the list at this _response
441+
position_ is not known to be complete. Clients should expect the GraphQL Service
442+
to incrementally deliver the remainder list items of this list. When the pending
443+
result is associated with a `@defer` directive, it indicates that the response
444+
fields contained in the deferred fragment are not known to be complete. Clients
445+
should expect the GraphQL Service to incrementally deliver the remainder of the
446+
fields contained in the deferred fragment at this _response position_.
436447

437448
If the associated `@defer` or `@stream` directive contains a `label` argument,
438449
the pending result must contain an entry {"label"} with the value of this
@@ -445,14 +456,9 @@ this data, and the data can be found either in the {"data"} entry in the
445456
_initial incremental stream result_, or one of the prior _incremental stream
446457
update result_ in the _incremental stream_.
447458

448-
:: The _associated pending result_ is a specific _pending result_ associated
449-
with any given _incremental result_ or _completed result_. The associated
450-
pending result can be determined by finding the pending result where the value
451-
of its {"id"} entry is the same value of the {"id"} entry of the given
452-
incremental result or completed result. The associated pending result must
453-
appear in the _incremental stream_, in the same or prior _initial incremental
454-
stream result_ or _execution update result_ as the given incremental result or
455-
completed result.
459+
:: The _associated pending result_ of an _incremental result_ or _completed
460+
result_ is the _pending result_ whose {"id"} entry has the same value as the
461+
{"id"} entry of the given incremental result or completed result.
456462

457463
### Incremental Result
458464

@@ -462,10 +468,11 @@ _incremental list result_ or an _incremental object result_.
462468

463469
An _incremental result_ must be a map.
464470

465-
Every _incremental result_ must contain an entry with the key {"id"} with a
466-
string value. The definition of _associated pending result_ describes how this
467-
value is used to determine the associated pending result for a given
468-
_incremental result_.
471+
Every _incremental result_ must contain an entry with the key {"id"}, the value
472+
of which is a string referencing its _associated pending result_. The associated
473+
pending result must appear either in the _initial incremental stream result_, in
474+
a prior _incremental stream update result_, or in the same _incremental stream
475+
update result_ as the _incremental result_ that references it.
469476

470477
#### Incremental List Result
471478

@@ -479,25 +486,25 @@ from its _associated pending result_.
479486

480487
**Incremental List Result Format**
481488

482-
Every _incremental list result_ must contain an entry with the key {"id"}, used
483-
to determine the _associated pending result_ for this _incremental result_.
484-
485489
Every _incremental list result_ must contain an {"items"} entry. The {"items"}
486490
entry must contain a list of additional list items for the list field in the
487491
incremental list result's _response position_. The value of this entry must be a
488492
list of the same type of the response field at this _response position_.
489493

490494
If any _execution error_ were raised during the execution of the results in
491-
{"items"} and these errors propagate to a _response position_ higher than the
492-
_incremental list result_'s response position, the incremental list result is
493-
considered failed and should not be included in the _incremental stream_. The
494-
errors that caused this failure will be included in a _completed result_.
495+
{"items"} and these errors propagate to the _response position_ of the
496+
_incremental list result_ (i.e. the streamed list), or a parent response
497+
position of the incremental list result's response position (i.e. a parent of
498+
the streamed list), the incremental list result is considered failed and should
499+
not be included in the _incremental stream_. The errors that caused this failure
500+
will be included in a _completed result_.
495501

496502
If any _execution error_ were raised during the execution of the results in
497-
{"items"} and these errors did not propagate to a path higher than the
498-
_incremental list result_'s path, the incremental list result must contain an
499-
entry with key {"errors"} containing these execution errors. The value of this
500-
entry is described in the "Errors" section.
503+
{"items"} and no such error propagated to the _response position_ of the
504+
_incremental list result_, or a parent response position of the incremental list
505+
result's response position, the incremental list result must contain an entry
506+
with key {"errors"} containing these execution errors. The value of this entry
507+
is described in the "Errors" section.
501508

502509
#### Incremental Object Result
503510

@@ -508,34 +515,38 @@ result_ must be associated with a `@defer` directive.
508515

509516
**Incremental Object Result Format**
510517

511-
The _incremental object result_ may contain a {"subPath"} entry. If this entry
512-
is present, the incremental object result's _response position_ can be
513-
determined by concatenating the value of the _associated pending result_'s
514-
{"path"} entry with the value of this {"subPath"} entry. If no {"subPath"} entry
515-
is present, the _response position_ is the value of the associated pending
516-
result's {"path"} entry.
518+
The _incremental object result_ may contain a {"subPath"} entry. If such an
519+
entry is present, the _response position_ of the incremental object result is
520+
the result of appending the value of this {"subPath"} to the value of the
521+
{"path"} entry of the _associated pending result_. If no {"subPath"} entry is
522+
present, the _response position_ is the value of the associated pending result's
523+
{"path"} entry.
517524

518525
An _incremental object result_ may be used to deliver data for response fields
519-
that were contained in more than one deferred fragments. In that case, the
520-
_associated pending result_ of the incremental object result must be a _pending
521-
result_ with the longest {"path"}.
526+
that were contained in more than one deferred fragment.
527+
528+
In that case, the _associated pending result_ of the incremental object result
529+
must be one of the _pending result_ that corresponding to a fragment that
530+
contained the delivered responsive fields. If any of these pending results have
531+
a {"path"} of varying length, one of the pending results with the longest
532+
{"path"} must be chosen to minimize the size of the {"subPath"}.
522533

523534
Every _incremental object result_ must contain a {"data"} entry. The {"data"}
524535
entry must contain a map of additional response fields. The {"data"} entry in an
525536
incremental object result will be of the type of the field at the incremental
526537
object result's _response position_.
527538

528539
If any _execution error_ were raised during the execution of the results in
529-
{"data"} and these errors propagated to a _response position_ higher than the
540+
{"data"} and these errors propagated to a parent _response position_ of the
530541
_incremental object result_'s response position, the incremental object result
531542
is considered failed and should not be included in the incremental stream. The
532-
errors that caused this failure will be included in a _completed result_.
543+
error that caused this failure will be included in a _completed result_.
533544

534545
If any _execution error_ were raised during the execution of the results in
535-
{"data"} and these errors did not propagate to a _response position_ higher than
536-
the _incremental object result_'s response position, the incremental object
537-
result must contain an entry with key {"errors"} containing these execution
538-
errors. The value of this entry is described in the "Errors" section.
546+
{"data"} and no such error propagated to a parent _response position_ of the
547+
_incremental object result_'s response position, the incremental object result
548+
must contain an entry with key {"errors"} containing these execution errors. The
549+
value of this entry is described in the "Errors" section.
539550

540551
### Completed Result
541552

@@ -549,16 +560,20 @@ which this completed result appears.
549560

550561
A _completed result_ must be a map.
551562

552-
Every _completed result_ must contain an entry with the key {"id"} with a string
553-
value. The definition of _associated pending result_ describes how this value is
554-
used to determine the associated pending result for a given _completed result_.
563+
A _completed result_ must contain an entry with the key {"id"}, and may contain
564+
an entry with the key {"errors"}.
565+
566+
The value of {"id"} must be a string referencing its _associated pending
567+
result_. The associated pending result must appear either in the _initial
568+
incremental stream result_, in a prior _incremental stream update result_, or in
569+
the same _incremental stream update result_ as the _completed result_ that
570+
references it.
555571

556-
A _completed result_ may contain an {"errors"} entry. When the {"errors"} entry
557-
is present, it informs clients that the delivery of the data from the
558-
_associated pending result_ has failed, due to an execution error propagating to
559-
a _response position_ higher than the _incremental result_'s response position.
560-
The {"errors"} entry must contain these execution errors. The value of this
561-
entry is described in the "Errors" section.
572+
The value of {"errors"}, if present, informs clients that the delivery of the
573+
data from the _associated pending result_ has failed, due to an execution error
574+
propagating to a parent _response position_ of the _incremental result_'s
575+
response position. The {"errors"} entry must contain these execution errors. The
576+
value of this entry is described in the "Errors" section.
562577

563578
### Additional Entries
564579

0 commit comments

Comments
 (0)