Spec: Formal Subscriptions Definition #305
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -198,6 +198,67 @@ query getName { | |
| } | ||
| ``` | ||
|
|
||
| ### Subscription Operation Definitions | ||
|
|
||
| #### Single root field | ||
|
|
||
| **Formal Specification** | ||
|
|
||
| * For each subscription operation definition {subscription} in the document | ||
| * Let {rootFields} be the top level selection set on {subscription}. | ||
| * {rootFields} must be a set of one. | ||
|
|
||
| **Explanatory Text** | ||
|
|
||
| Subscription operations must have exactly one root field. | ||
|
There was a problem hiding this comment. @robzhu what is the reason for that? why can't i subscribe to more then one subscription with one call? There was a problem hiding this comment. I agree with Rob's text that starting with just one root field is reasonable. A later version of the spec could support multiple fields, but that requires figuring out a lot of edge cases around errors, when subfields are re-executed, and more. There was a problem hiding this comment. I also would like to know the reason for this rule. I find that it is quite hard limitation, and in a way it goes against GraphQL principles where clients have the power to decide what it wants to get.
I think it would be helpful to list and discuss these edge cases. From my experience, there are definitely things to consider when merging different event streams from different GraphQL subscription fields, but I find it quite manageable. There was a problem hiding this comment. I listed most of the points I found as I was implementing it in sangria here: I think that it boils down to points IMHO, if we need to make a trade off, I would rather disallow not-null root subscription field types than allow only a single subscription field in a query. There was a problem hiding this comment. @stubailo if one wants to experiment that's fine, but i don't think it should be in the official spec unless there is a reason (which is not implementation) behind it. There was a problem hiding this comment. @stubailo thanks a lot for describing in on an example!
I don't see it as a problem but rather as a natural behavior. This is inherent property of event-based interaction. This is also the reason why I suggested to disallow not-null root subscription field types.
I also don't see it as a issue either. Can you describe in more detail why this behavior can be disadvantageous? (considering that you still can make 2 separate and isolated subscription queries if it suits better for the use-case at hand)
I feel that either behavior is fine as long as it is defined in the spec. Though in this case I would suggest draw inspiration from streaming libraries: if 2 event streams are joined/merged together in a single result stream, then an error in either of these will also case the result stream to fail. If one of event steams naturally completes (because of the exhaustion), then the result steam still continue to emit events until all of the source streams are exhausted. I think this behavior is quite intuitive and widespread. There was a problem hiding this comment. @OlegIlyenko @DxCx To give a little bit of context on where this came from, we discovered early on that it was better to use subscriptions for modeling granular events. For example, consider the three main subscriptions that operate on a facebook post: live comments, live likes, and typing indicators. These are individual subscriptions as opposed to a single "postLiveUpdate" subscription. Keeping these subscriptions granular on the client made natural sense. @laneyk and @dschafer may be able to add more perspective here. Thinking this through, if we include multiple root fields like so: subscription sub(...) {
liveLike (...) {...}
likeComment (...) {...}
}So far, everyone seems to assume this subscription should publish data when either "live like" or "live comment" publishes. Is that clearly the intent of this query? What if there were a desire to trigger the publish only when both root fields have a publish payload available? How would we describe that? By limiting the selection to a single root field, we sidestep all that. I also don't think the single-root-field-rule introduces any practical limitations to the client. In fact, it results in simpler client-side code, like so: likeSubscription.subscribe(payload => updateLikeState(payload));For subscriptions containing more than one root field, if we assume the "or" behavior, as @stubailo points out, you'll never have more than one event trigger at a time, so the code would end up looking like: genericSubscription.subscribe(payload => {
if (payload.subscriptionA) { updateA(payload.SubscriptionA); }
else if (payload.subscriptionB) { updateB(payload.SubscriptionB); }
// etc.
});Can someone help me understand a compelling use case that is served by multi-root subscription operations that would not be equally served by separate individual subscriptions? There was a problem hiding this comment. Just to add a meta-point to this conversation: In my view, there's nothing stopping us from working through these details and figuring out the edge and corner cases of allowing multiple subscription fields in a single request, however the choice we do have is to address those concerns now, or allow for more time to do so. In previous conversations @robzhu has had over the last few months about subscriptions, he has convinced many that this is far more complicated than we originally thought and may not have clear answers. This limitation is added mostly in a desire to expedite the addition of subscriptions to the spec, while reserving the ability to continue to work out how or if multi-field subscriptions should be allowed. Had this limitations been omitted while also not making mention of how to address multi-field subscriptions in the spec, then we would see divergence of behavior and that could tie our hands in the future for deciding how to address these edge cases. There was a problem hiding this comment. Thanks a lot @robzhu and @leebyron for the insightful comments! I think now I got a better understanding of the issue. I was also in two minds on this. On one hand, I wanted to get a better understanding about motivation behind inclusion of this rule. But on the other hand, I don't want to delay the progress on subscriptions incision in the spec. I tend to agree that it is a good idea to disallow multiple fields for now and start a separate discussion. I think it is a discussion worth having. I am actually very glad that this point is considered in the spec since I was also quite concerned about the semantics of multiple subscriptions fields.
In general, I found it very valuable to have as much information from client as possible in single query. For example, the fact that a client can express its requirements for a view or particular part of the application in a single query allowed us to make very interesting optimizations which would be quite hard to do otherwise (it is quite hard to correlate seemingly independent requests/queries). So by allowing client to better express it's requirements with several subscription fields in a single query, we open a door for potential server-side optimizations. Now that I'm equipped with new insights, I will give it another thought. This thread was definitely helpful in this respect. Before we will introduce this rule though, I think it is important to consider the nullability of the subscription fields, as i mentioned above. It is possible to make a nullable field not-null later on in a backwards-compatible way. If we allow subscription fields to be not-null now, it might become a challenge in future to allow multiple subscription fields, if we decide to do so. There was a problem hiding this comment. Nullability may mean two different things in this context - this is a great point we should address. One thing it may mean is that a subscription may not exist given some inputs in a way that isn't considered an error. I think this interpretation is both not what you were referring to, and also probably confusing to think about. The schema talks about the type of the payload result - so we're talking about the types of responses. We should probably make this point in the spec to clarify. Secondly the nullability of the responses. This is one of the concerns with multi-field subscriptions to address later. For example, should it be legal to have a subscription field I think handling the payloads of multi-field subscriptions will need to account for this |
||
|
|
||
| Valid examples: | ||
|
|
||
| ```graphql | ||
| subscription sub { | ||
| newMessage { | ||
| body | ||
| sender | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```graphql | ||
| fragment newMessageFields on Message { | ||
| body | ||
| sender | ||
| } | ||
|
|
||
| subscription sub { | ||
| newMessage { | ||
| ... newMessageFields | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Invalid: | ||
|
|
||
| ```!graphql | ||
| subscription sub { | ||
| newMessage { | ||
| body | ||
| sender | ||
| } | ||
| disallowedSecondRootField | ||
| } | ||
| ``` | ||
|
|
||
| Introspection fields are counted. The following example is also invalid: | ||
|
|
||
| ```!graphql | ||
| subscription sub { | ||
| newMessage { | ||
| body | ||
| sender | ||
| } | ||
| __typename | ||
|
There was a problem hiding this comment. Not clear what we would name this one if we wanted to get rid of the comment. There was a problem hiding this comment. Added a description above. |
||
| } | ||
| ``` | ||
|
|
||
| ## Fields | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
to recycle terms, how about: "a long-lived request that fetches data in response to source events."