Editorial changes for Event Streams #1099
Conversation
✅ Deploy Preview for graphql-spec-draft ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
leebyron
force-pushed
the
streams-editorial
branch
2 times, most recently
from
bd84927
to
6c52b20
Compare
leebyron
added
✏️ Editorial
leebyron
force-pushed
the
streams-editorial
branch
from
6c52b20
to
58aa3ae
Compare
There was a problem hiding this comment.
I think this is a massively clarifying PR!
I got hung up for a bit on the three verbs ("complete normally", "complete with error" and "cancel") and in particular trying to figure out the practical difference between "complete normally" and "cancel", but I think they ultimately make sense. My main concern is ensuring we've handled all the situations:
| stream | event | handler |
|---|---|---|
| sourceStream | completes normally | complete responseStream normally |
| sourceStream | completes with error | complete responseStream with error |
| sourceStream | is cancelled | unhandled, since can only occur from responseStream being cancelled ❔ |
| sourceStream | encounters error | forces complete with error -> handled above |
| responseStream | completes normally | unhandled, since can only occur from sourceStream completing |
| responseStream | completes with error | unhandled, occurs from sourceStream completing with error |
| responseStream | is cancelled | cancel sourceStream |
| responseStream | encounters error | forces complete with error -> unhandled above |
Is there a situation in which responseStream might encounter an error (other than from sourceStream encountering an error)? If so, this is currently unhandled, I think?
Are there any other ways for sourceStream to be cancelled? I assume user code cancelling it would be seen by us as "completes normally"? (If so, this might warrant a non-normative note?)
| the subscription. | ||
| receive payloads for a subscription. This in turn also cancels the Source | ||
| Stream, which is a good opportunity to clean up any other resources used by the | ||
| subscription. |
There was a problem hiding this comment.
This is a concrete change from "may" cancel the source stream to "does" cancel the source stream.
We create the source stream in the CreateSourceEventStream algorithm, so it is definitely our responsibility to also ensure it is released (completed). This new wording covers this, the old wording was essentially incorrect. I support this change.
There was a problem hiding this comment.
Exactly, the previous wording was too loose. Ultimately this is not observable behavior from an API consumer's point of view, so also not spec enforceable, but I think this language is much more clear. If a resulting stream consumer cancels, then it's certainly the case that the source stream must be made aware of that.
Extra unnecessary detail in case if ever comes up: if an implementer doesn't want to cancel the source stream, they should be using an intermediate like tee
|
Oh I merged in the latest |
|
@benjie thanks for the detailed thoughts, responding to your comment further above:
The practical difference is the origin and "direction" of the event. A completion is a stream emitter communicating that no further emit events will occur (either because the stream is completed normally, or because of an error). However a cancel is a stream consumer communicating that they are no longer interested in receiving events. The behavior described here is that after a stream emitter receives a cancel that it should pass that event along "backwards" relative to the flow of events. There is no "forwards" version, so there is no unhandled case of the source stream cancelling
You are correct, it's missing that
That's right, and good suggestion. revising your table, these are the four observable events from the perspective of creating responseStream:
and these are removed from your table, they are not observable events from this perspective:
|
This makes a few changes to the Subscriptions section where we're talking about event streams in an attempt to make it more clear about what's going on. - Revised variable names from "fieldStream" to "sourceStream" to make it easier to trace variables through algorithms. - Rewrote the "Event Streams" definition to be more clear about "emit" keyword and have clear paragraphs on completion and cancellation. - Rewrote the `MapSourceToResponseEvent` algorithm to be a correctly formatted algorithm with a return statement at the end. Introduced a new "When" keyword to describe event subscriptions. Added explicit sections on passing back cancellation (discussed in WG) as well as completion with error (not discussed, but I realized was also left ambiguous)
leebyron
force-pushed
the
streams-editorial
branch
from
36e5f99
to
75f10e0
Compare
| - If internal {error} was raised: | ||
| - Cancel {sourceStream}. | ||
| - Complete {responseStream} with {error}. |
There was a problem hiding this comment.
See the note below, but I checked with graphql-js and this aligns. Request errors occur before field execution begins, which for subscriptions would be before source stream is created. Then each event through the subscription could produce field errors, but those are handled normally as { data, errors } and shouldn't complete the subscription. The only remaining scenario is some internal exceptional event.
I thought about continuing to leave this omitted, since it makes sense why it was omitted before, but I do agree that this is more clear about what to do in this non-normative scenario, and will make it more clear in the future if we ever decide to formally add "fatal error" as an error type
There was a problem hiding this comment.
I'm not 100% clear on what kind of internal error is being envisioned here. It seems like it's clearly not a request or field error, as explicitly stated above.
Is this analogous to the case of the graphql-js call to asyncIterator.next() resulting in an exception? I would think that's covered below when discussing "completing in error" but maybe that's not the case?
Of course, anything could error => maybe it just means "something else went wrong?" And we are making how to handle that more explicit in the case of a subscription than we would with regard to our other operation, because it is helpful to clients to understand how this case is handled in the context of the response stream?
There was a problem hiding this comment.
@yaacovCR that last bit you said is exactly right. The vast amount of our spec assumes algorithms are pretty typical functions which you call with arguments and return a value, and the most significant complication is the introduction of async functions (which the spec really leaves mostly unstated), so the novelty here is the fact that this algorithm is not returning the result but returning a stream which will contain results. That's important because for a typical function we can just say if there is some exceptional error in any given algorithm that it should work its way up until something explicitly handles it or it fatals the whole operation - that's how error handling works (in some way or another) in just about every language and environment.
However it's a lot less obvious what should happen for a stream which encounters an exceptional error after that particular creation algorithm has completed - what is the right behavior? This tries to be explicit to avoid that ambiguity - we should make sure the resulting stream also ends with an error.
Is this analogous to the case of the graphql-js call to asyncIterator.next() resulting in an exception?
Yes - but specifically inside where it is being mapped. graphql-js handles field errors during execution of a single subscription payload, resulting in a {data: null, errors} normal payload, but other exceptions could trigger this codepath. That's really what's being described here
| - When {sourceStream} completes normally: | ||
| - Complete {responseStream} normally. | ||
| - When {sourceStream} completes with {error}: | ||
| - Complete {responseStream} with {error}. |
There was a problem hiding this comment.
Does this wording imply that when the {responseStream} completes with error, it must do so in the same manner as when the {sourceStream} does? We have a request at graphql-js for emitting well formated GraphQLErrors instead of throwing. I would read the specification permissively, as in the manner in which the {responseStream} completes with said error is up to the implementation, allowing that change.
Once could argue instead/additionally that it belongs within the transport protocol specification.
Tagging @leebyron @enisdenjo @aseemk from the linked issue.
There was a problem hiding this comment.
From the SSE perspective, and in the GraphQL over SSE RFC, errors are emitted over the stream as an event.
This is because browser native EventSource will not report back to the user non-200 responses in detail - it'll just say "error" - leaving the user in the dark. Furthermore, if the error occurs after a while during the stream, the connection is already established and the only way to report an issue is in form of an event.
Same thing applies for WebSockets.
There was a problem hiding this comment.
I agree that for normal errors in sourceStream we should capture them and emit an { errors: [ ... ] } payload rather than terminating with an error.
| - Complete {responseStream} with {error}. | |
| - Let {errors} be a list containing {error}. | |
| - Let {response} be an unordered map containing {errors}. | |
| - Emit {response} on {responseStream}. | |
| - Complete {responseStream} normally. |
However, this is a change in behavior (not an editorial change like the rest of this PR), so perhaps this should be raised after this editorial only change is merged - see #1127 for a suitable follow-up PR.
There was a problem hiding this comment.
I agree that for normal errors in sourceStream we should capture them and emit an { errors: [ ... ] } payload rather than terminating with an error.
Generally agree with using the GraphQL response structure to convey errors but that makes me question why we would need anything else. Is there any specific reason to keep the Complete {responseStream} with {error} just above?
There was a problem hiding this comment.
I'm not certain, but I imagine that an internal error implies that something fundamental has gone wrong and thus we're no longer sure that we can even complete the request correctly - a bit like returning a "500 Internal Server Error" rather than a 4xx error in HTTP: "something really really went wrong and we're just giving up right here and exiting immediately". Perhaps we can't even be trusted to form a GraphQL response payload at this point - perhaps it was attempting to form such a payload that caused the internal error in the first place?
There was a problem hiding this comment.
@yaacovCR I've seen that comment but not being super familiar with graphql-js, I'm not sure I understand all the subtleties of it. Once we have graphql/graphql-js#4302, are there still places where graphql-js can throw? I thought this was the last one.
There was a problem hiding this comment.
That’s correct, there are no additional places where we expect graphql-js to throw from user code exceptions, but what about our own code and it’s unexpected exceptions?
My understanding of the comment above was that internal errors referred to that scenario, which we cannot model within the reference implementation. (We cannot catch those errors, because the catching code could also throw an error.) At least, that’s my understanding!
There was a problem hiding this comment.
Should we move this discussion to #1127 as it does not seem to be editorial but a change in behavior?
There was a problem hiding this comment.
This is also very related to graphql/graphql-js#4001. Happy to consolidate everything to #1127. Edit: done here
There was a problem hiding this comment.
*Not really making a point, just giving context from the transport perspective.
When dealing with HTTP request-response format, we have 2 places conveying information (as per GQL over HTTP): the body (data) and the headers (metadata). As @benjie said, 4XX and 5XX would indicate the severity of the errors in data.
However, in streaming transports this is different. When dealing with both WS and SSE, browser native implementations (WebSocket and EventSource respectively) give out less information about termination of requests. WebSocket's close event is limited in size, so you cannot send a big error message; and EventSource will tell you absolutely nothing if the server responds with a non-200 status.
Multipart/incremental-delivery/custom-SSE are different because the user does the heavy-lifting (implementation of the fetcher and parser) and there you certainly can use headers for metadata.
This makes a few changes to the Subscriptions section where we're talking about event streams in an attempt to make it more clear about what's going on.
Revised variable names from "fieldStream" to "sourceStream" to make it easier to trace variables through algorithms.
Rewrote the "Event Streams" definition to be more clear about "emit" keyword and have clear paragraphs on completion and cancellation.
Rewrote the
MapSourceToResponseEventalgorithm to be a correctly formatted algorithm with a return statement at the end. Introduced a new "When" keyword to describe event subscriptions. Added explicit sections on passing back cancellation (discussed in WG) as well as completion with error (not discussed, but I realized was also left ambiguous)