Spec: Formal Subscriptions Definition

spec/Section 5 -- Validation.md

@@ -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.
+
+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
+}
+```
 
 ## Fields
 

spec/Section 6 -- Execution.md

@@ -103,8 +103,9 @@ Note: This algorithm is very similar to {CoerceArgumentValues()}.
 ## Executing Operations
 
 The type system, as described in the “Type System” section of the spec, must
-provide a query root object type. If mutations are supported, it must also
-provide a mutation root object type.
+provide a query root object type. If mutations or subscriptions are supported, it must also provide a mutation and subscription root object type, respectively.
+
+### Query
 
 If the operation is a query, the result of the operation is the result of
 executing the query’s top level selection set with the query root object type.
@@ -123,6 +124,8 @@ ExecuteQuery(query, schema, variableValues, initialValue):
     selection set.
   * Return an unordered map containing {data} and {errors}.
 
+### Mutation
+
 If the operation is a mutation, the result of the operation is the result of
 executing the mutation’s top level selection set on the mutation root
 object type. This selection set should be executed serially.
@@ -143,6 +146,120 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):
     selection set.
   * Return an unordered map containing {data} and {errors}.
 
+### Subscription
+
+We define an event stream as a sequence of discrete events over time that can be
+observed. An observer of an event stream may cancel observation to avoid stop
+future events.
+
+If the operation is a subscription, the result is an event stream called the
+"Publish Stream" where each event in the stream is called a "Publish Payload".
+
+#### Subscribe
+
+Executing a subscription creates a persistent function on the server that
+maps an underlying event stream to the Publish Stream. The logic to create the
+underlying event stream is domain-specific and takes the root field and query
+variables as inputs.
+
+Subscribe(schema, subscription, operationName, 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 {eventStream} be the result of running {CreateUnderlyingEventStream(rootField, variableValues)}.
+  * Let {publishStream} be the result of running {MapEventToPayload(eventStream)}
+
+CreateUnderlyingEventStream(rootField, variableValues):
+
+  * *Application-specific logic to map from root field/variables to events*
+
+#### Publish Stream
+
+Each event in the underlying event stream triggers execution of the subscription
+selection set.
+
+MapEventToPayload(eventStream):
+
+  * For each {event} on {eventStream}:
+    * Let {publishPayload} be the result of running
+      {ExecuteSelectionSet(selectionSet, subscriptionType, event, variableValues)}
+      *normally* (allowing parallelization).
+    * Let {errors} be any *field errors* produced while executing the
+      selection set.
+    * Yield an unordered map containing {publishPayload} and, optionally,
+      {errors} on {publishStream}.
+  * At any time while the publish stream is active, the client or server may
+  Unsubscribe().
+
+Common reasons for Unsubscribe() include:
+  * client no longer wants to receive payloads for a subscription.
+  * The underlying event stream has produced an error or has naturally ended.
+
+#### Unsubscribe
+
+Unsubscribe cancels the Publish Stream. This is also a good opportunity for the
+server to clean up the underlying event stream and any other resources used by
+the subscription.
+
+Unsubscribe()
+
+  * Cancel {publishStream}
+
+#### Example
+
+As an example, consider a chat application. To subscribe to new messages posted
+to the chat room, the client sends a request like so:
+
+```graphql
+subscription NewMessages {
+  newMessage(roomId: 123) {
+    sender
+    text
+  }
+}
+```
+
+While the client is subscribe, whenever new messages are posted to chat room
+with ID "123", the selection for "sender" and "text" will be evaluated and
+published to the client, for example:
+
+```js
+{
+  "data": {
+    "newMessage": {
+      "sender": "Hagrid",
+      "text": "You're a wizard!"
+    }
+  }
+}
+```
+
+#### Recommendations and Considerations for Supporting Subscriptions
+
+Supporting subscriptions is a large change for any GraphQL server. Query and
+mutation operations are stateless, allowing scaling via cloning GraphQL server
+instances. Subscriptions, by contrast, are stateful. The pieces of state for a
+subscription are:
+
+  * Subscriber/client channel
+  * Subscription document
+  * Variables
+  * Execution context (for example, current logged-in user, locale, etc.)
+  * Event stream resulting from Subscribe step (above)
+
+We recommend thinking about the behavior of your system when this state is lost
+due to single-node failures. We can improve durability and availability by using
+dedicated sub-systems to manage this state. For example, event streams can be
+built using modern pub-sub systems, and payload delivery to clients can be
+handled by a dedicated client gateway tier.
+
+For systems with high capacity, availability, and durability requirements, we
+recommend keeping the GraphQL server stateless and delegating all state
+persistence to sub-systems that are designed for stateful scaling. Note that
+subscription types are still defined in the original schema along with queries
+and mutations.
 
 ## Executing Selection Sets