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,10 @@ 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 +125,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 +147,136 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):
     selection set.
   * Return an unordered map containing {data} and {errors}.
 
+### Subscription
+
+If the operation is a subscription, the result is an event stream called the
+"Response Stream" where each event in the event stream is the result of
+executing the operation for each new event on an underlying "Source Stream".
+
+An event stream represents a sequence of discrete events over time which can be
+observed. As an example, a "Pub-Sub" system may produce an event stream when
+"subscribing to a topic", with an event occurring on that event stream for each
+"publish" to that topic. Event streams may produce an infinite sequence of
+events or may complete at any point. Event streams may complete in response to
+an error or simply because no more events will occur. An observer may at any
+point decide to stop observing an event stream, after which it must receive no
+more events from that event stream.
+
+Note: If an event stream's observer has stopped observing, that may be a good
+opportunity to clean up any associated resources such as closing any connections
+which are no longer necessary.
+
+#### Subscribe
+
+Executing a subscription creates a persistent function on the server that
+maps an underlying Source stream to the Publish Stream. The logic to create the
+Source stream is application-specific and takes the root field and query
+variables as inputs.
+
+Subscribe(subscription, schema, variableValues, initialValue):
+
+  * Let {sourceStream} be the result of running {CreateSourceEventStream(subscription, schema, variableValues, initialValue)}.
+  * Let {responseStream} be the result of running {MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues)}
+  * Return {responseStream}.
+
+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)}.
+  * Return {fieldStream}.
+
+ResolveFieldEventStream(subscriptionType, rootValue, fieldName, argumentValues):
+  * Let {resolver} be the internal function provided by {subscriptionType} for
+    determining the resolved value of a field named {fieldName}.
+  * Return the result of calling {resolver}, providing {rootValue} and {argumentValues}.
+
+#### Publish Stream
+
+Each event in the underlying event stream triggers execution of the subscription
+selection set.
+
+MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues):
+
+  * Return a new event stream {responseStream} which yields events as follows:
+  * For each {event} on {sourceStream}:
+    * Let {response} be the result of running
+      {ExecuteSubscriptionEvent(subscription, schema, variableValues, event)}.
+    * Yield an event containing {response}.
+
+ExecuteSubscriptionEvent(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 {data} be the result of running
+    {ExecuteSelectionSet(selectionSet, subscriptionType, initialValue, variableValues)}
+    *normally* (allowing parallelization).
+  * Let {errors} be any *field errors* produced while executing the
+    selection set.
+  * Return an unordered map containing {data} and {errors}.
+
+Note: in large scale subscription systems, the {ExecuteSubscriptionEvent} and
+{Subscribe} algorithms may be run on separate services to maintain predictable
+scaling properties. See the section below on Supporting Subscriptions at Scale.
+
+#### Unsubscribe
+
+Unsubscribe cancels the Response 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. Here are some example cases in which to Unsubscribe: client
+no longer wishes to receive payloads for a subscription; the source event stream
+produced an error or naturally ended; the server encountered an error during
+ExecuteSubscriptionEvent.
+
+Unsubscribe()
+
+  * Cancel {responseStream}
+
+#### 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!"
+    }
+  }
+}
+```
+
+#### Supporting Subscriptions at Scale
+
+Supporting subscriptions is a significant change for any GraphQL server. Query
+and mutation operations are stateless, allowing scaling via cloning GraphQL
+server instances. Subscriptions, by contrast, are stateful and require
+maintaining the GraphQL document, variables, and other context over the lifetime
+of the subscription.
+
+Consider the behavior of your system when state is lost due to the failure of a
+single machine in a service. Durability and availability may be improved by
+having separate dedicated services for managing subscription state and client
+connectivity.
 
 ## Executing Selection Sets