Subscriptions: Final edits (#392)

* Subscriptions: Final edits

This does a last pass over the subscriptions specification to clean up some ambiguities and crisp up some language.

Two important things to take note of:

1. The `CreateSourceEventStream` algo was underspecified and did not articulate how fields should be collected from the selection set. This makes it clear that `CollectFields` is used, just like any other selection set. It also did not describe behavior when executing an invalid query, this adds that a query-level error should be thrown.

2. The Subscription Operation validation is similarly underspecified, and does not describe what should happen if a fragment spread is found as the first selection in a selection set. This clarifies that it is *fields* that exactly one is expected, rather than selections.

* Add note about GetOperation()

Author: leebyron

spec/Section 3 -- Type System.md

@@ -1019,11 +1019,11 @@ must *not* be queried if either the `@skip` condition is true *or* the
 A GraphQL schema includes types, indicating where query, mutation, and
 subscription operations start. This provides the initial entry points into the
 type system. The query type must always be provided, and is an Object
-base type. The mutation type is optional; if it is null, that means
+base type. The mutation type is optional; if it is not provided, that means
 the system does not support mutations. If it is provided, it must
 be an object base type. Similarly, the subscription type is optional; if it is
-null, the system does not support subscriptions. If it is provided, it must be
-an object base type.
+not provided, the system does not support subscriptions. If it is provided, it
+must be an object base type.
 
 The fields on the query type indicate what fields are available at
 the top level of a GraphQL query. For example, a basic GraphQL query

spec/Section 5 -- Validation.md

@@ -205,8 +205,12 @@ query getName {
 **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.
+  * Let {subscriptionType} be the root Subscription type in {schema}.
+  * Let {selectionSet} be the top level selection set on {subscription}.
+  * Let {variableValues} be the empty set.
+  * Let {groupedFieldSet} be the result of
+    {CollectFields(subscriptionType, selectionSet, variableValues)}.
+  * {groupedFieldSet} must have exactly one entry.
 
 **Explanatory Text**
 
@@ -224,14 +228,14 @@ subscription sub {
 ```
 
 ```graphql example
-fragment newMessageFields on Message {
-  body
-  sender
+subscription sub {
+  ...newMessageFields
 }
 
-subscription sub {
+fragment newMessageFields on Subscription {
   newMessage {
-    ... newMessageFields
+    body
+    sender
   }
 }
 ```
@@ -248,6 +252,20 @@ subscription sub {
 }
 ```
 
+```graphql counter-example
+subscription sub {
+  ...multipleSubscriptions
+}
+
+fragment multipleSubscriptions on Subscription {
+  newMessage {
+    body
+    sender
+  }
+  disallowedSecondRootField
+}
+```
+
 Introspection fields are counted. The following example is also invalid:
 
 ```graphql counter-example
@@ -260,6 +278,11 @@ subscription sub {
 }
 ```
 
+Note: While each subscription must have exactly one root field, a document may
+contain any number of operations, each of which may contain different root
+fields. When executed, a document containing multiple subscription operations
+must provide the operation name as described in {GetOperation()}.
+
 ## Fields
 
 ### Field Selections on Objects, Interfaces, and Unions Types

spec/Section 6 -- Execution.md

@@ -104,7 +104,7 @@ Note: This algorithm is very similar to {CoerceArgumentValues()}.
 
 ## Executing Operations
 
-The type system, as described in the “Type System” section of the spec, must
+The type system, as described in the "Type System" section of the spec, must
 provide a query root object type. If mutations or subscriptions are supported,
 it must also provide a mutation or subscription root object type, respectively.
 
@@ -212,7 +212,7 @@ must receive no more events from that event stream.
 
 **Supporting Subscriptions at Scale**
 
-Supporting subscriptions is a significant change for any GraphQL server. Query
+Supporting subscriptions is a significant change for any GraphQL service. Query
 and mutation operations are stateless, allowing scaling via cloning of GraphQL
 server instances. Subscriptions, by contrast, are stateful and require
 maintaining the GraphQL document, variables, and other context over the lifetime
@@ -233,10 +233,15 @@ CreateSourceEventStream(subscription, schema, variableValues, initialValue):
 
   * Let {subscriptionType} be the root Subscription type in {schema}.
   * Assert: {subscriptionType} is an Object type.
-  * Let {selectionSet} be the top level Selection Set in {subscription}.
-  * Let {rootField} be the first top level field in {selectionSet}.
-  * Let {argumentValues} be the result of {CoerceArgumentValues(subscriptionType, rootField, variableValues)}.
-  * Let {fieldStream} be the result of running {ResolveFieldEventStream(subscriptionType, initialValue, rootField, argumentValues)}.
+  * Let {groupedFieldSet} be the result of
+    {CollectFields(subscriptionType, selectionSet, variableValues)}.
+  * If {groupedFieldSet} does not have exactly one entry, throw a query error.
+  * Let {fields} be the value of the first entry in {groupedFieldSet}.
+  * Let {fieldName} be the name of the first entry in {fields}.
+    Note: This value is unaffected if an alias is used.
+  * Let {field} be the first entry in {fields}.
+  * Let {argumentValues} be the result of {CoerceArgumentValues(subscriptionType, field, variableValues)}
+  * Let {fieldStream} be the result of running {ResolveFieldEventStream(subscriptionType, initialValue, fieldName, argumentValues)}.
   * Return {fieldStream}.
 
 ResolveFieldEventStream(subscriptionType, rootValue, fieldName, argumentValues):
@@ -284,7 +289,7 @@ payloads for a subscription. This may in turn also cancel the Source Stream.
 This is also a good opportunity to clean up any other resources used by
 the subscription.
 
-Unsubscribe(responseStream)
+Unsubscribe(responseStream):
 
   * Cancel {responseStream}