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
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)