Merge remote-tracking branch 'martinbonnin/clarify-execution' into before-execution-begins-note

Author: benjie

spec/Section 6 -- Execution.md

@@ -18,10 +18,15 @@ A GraphQL service generates a response from a request via execution.
 - {extensions} (optional): A map reserved for implementation-specific additional
   information.
 
-Given this information, the result of {ExecuteRequest(schema, document,
+Given this information, the result of {ProcessRequest(schema, document,
 operationName, variableValues, initialValue)} produces the response, to be
 formatted according to the Response section below.
 
+:: Formally, _execution_ starts when executing the root selection set in
+{ExecuteRootSelectionSet()}. For convenience, this section also contains
+preliminary steps required for execution such as coercing variables or getting a
+source event stream.
+
 Implementations should not add additional properties to a _request_, which may
 conflict with future editions of the GraphQL specification. Instead,
 {extensions} provides a reserved location for implementation-specific additional
@@ -33,13 +38,13 @@ Note: GraphQL requests do not require any specific serialization format or
 transport mechanism. Message serialization and transport mechanisms should be
 chosen by the implementing service.
 
-## Executing Requests
+## Processing Requests
 
-To execute a request, the executor must have a parsed {Document} and a selected
+To process a request, the executor must have a parsed {Document} and a selected
 operation name to run if the document defines multiple operations, otherwise the
 document is expected to only contain a single operation. The result of the
-request is determined by the result of executing this operation according to the
-"Executing Operations” section below.
+request is determined by the result of processing this operation according to
+the "Processing Operations” section below.
 
 :: We define _execution_ as the process of executing the operation's root
 selection set through {ExecuteSelectionSet()}, thus _execution_ begins when
@@ -50,19 +55,20 @@ the _execution_ itself.
 Note: An error raised before _execution_ begins will typically be a _request
 error_, and once _execution_ begins will typically be a _field error_.
 
-ExecuteRequest(schema, document, operationName, variableValues, initialValue):
+ProcessRequest(schema, document, operationName, variableValues, initialValue):
 
 - Let {operation} be the result of {GetOperation(document, operationName)}.
 - Let {coercedVariableValues} be the result of {CoerceVariableValues(schema,
   operation, variableValues)}.
 - If {operation} is a query operation:
-  - Return {ExecuteQuery(operation, schema, coercedVariableValues,
+  - Return {ProcessQuery(operation, schema, coercedVariableValues,
     initialValue)}.
 - Otherwise if {operation} is a mutation operation:
-  - Return {ExecuteMutation(operation, schema, coercedVariableValues,
+  - Return {ProcessMutation(operation, schema, coercedVariableValues,
     initialValue)}.
 - Otherwise if {operation} is a subscription operation:
-  - Return {Subscribe(operation, schema, coercedVariableValues, initialValue)}.
+  - Return {ProcessSubscription(operation, schema, coercedVariableValues,
+    initialValue)}.
 
 GetOperation(document, operationName):
 
@@ -78,14 +84,14 @@ GetOperation(document, operationName):
 ### Validating Requests
 
 As explained in the Validation section, only requests which pass all validation
-rules should be executed. If validation errors are known, they should be
+rules should be processed. If validation errors are known, they should be
 reported in the list of "errors" in the response and the request must fail
-without _execution_.
+without processing.
 
 Typically validation is performed in the context of a request immediately before
-_execution_, however a GraphQL service may execute a request without immediately
+processing, however a GraphQL service may execute a process without immediately
 validating it if that exact same request is known to have been validated before.
-A GraphQL service should only execute requests which _at some point_ were known
+A GraphQL service should only process requests which _at some point_ were known
 to be free of any validation errors, and have since not changed.
 
 For example: the request may be validated during development, provided it does
@@ -132,7 +138,7 @@ CoerceVariableValues(schema, operation, variableValues):
 
 Note: This algorithm is very similar to {CoerceArgumentValues()}.
 
-## Executing Operations
+## Processing Operations
 
 The type system, as described in the "Type System" section of the spec, must
 provide a query root operation type. If mutations or subscriptions are
@@ -145,9 +151,9 @@ If the operation is a query, the result of the operation is the result of
 executing the operation’s _root selection set_ with the query root operation
 type.
 
-An initial value may be provided when executing a query operation.
+An initial value may be provided when processing a query operation.
 
-ExecuteQuery(query, schema, variableValues, initialValue):
+ProcessQuery(query, schema, variableValues, initialValue):
 
 - Let {queryType} be the root Query type in {schema}.
 - Assert: {queryType} is an Object type.
@@ -165,7 +171,7 @@ It is expected that the top level fields in a mutation operation perform
 side-effects on the underlying data system. Serial execution of the provided
 mutations ensures against race conditions during these side-effects.
 
-ExecuteMutation(mutation, schema, variableValues, initialValue):
+ProcessMutation(mutation, schema, variableValues, initialValue):
 
 - Let {mutationType} be the root Mutation type in {schema}.
 - Assert: {mutationType} is an Object type.
@@ -177,12 +183,13 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):
 
 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_.
+executing the operation’s root _selection set_ for each new event on an
+underlying _source stream_.
 
-Executing a subscription operation creates a persistent function on the service
+Processing a subscription operation creates a persistent function on the service
 that maps an underlying _source stream_ to a returned _response stream_.
 
-Subscribe(subscription, schema, variableValues, initialValue):
+ProcessSubscription(subscription, schema, variableValues, initialValue):
 
 - Let {sourceStream} be the result of running
   {CreateSourceEventStream(subscription, schema, variableValues, initialValue)}.
@@ -191,8 +198,8 @@ Subscribe(subscription, schema, variableValues, initialValue):
   variableValues)}.
 - Return {responseStream}.
 
-Note: In a large-scale subscription system, the {Subscribe()} and
-{ExecuteSubscriptionEvent()} algorithms may be run on separate services to
+Note: In a large-scale subscription system, the {ProcessSubscription()} and
+{ProcessSubscriptionEvent()} algorithms may be run on separate services to
 maintain predictable scaling properties. See the section below on Supporting
 Subscriptions at Scale.
 
@@ -313,7 +320,7 @@ MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues):
 - Let {responseStream} be a new _event stream_.
 - When {sourceStream} emits {sourceValue}:
   - Let {response} be the result of running
-    {ExecuteSubscriptionEvent(subscription, schema, variableValues,
+    {ProcessSubscriptionEvent(subscription, schema, variableValues,
     sourceValue)}.
   - If internal {error} was raised:
     - Cancel {sourceStream}.
@@ -328,21 +335,21 @@ MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues):
   - Complete {responseStream} normally.
 - Return {responseStream}.
 
-Note: Since {ExecuteSubscriptionEvent()} handles all _execution error_, and
+Note: Since {ProcessSubscriptionEvent()} handles all _execution error_, and
 _request error_ only occur during {CreateSourceEventStream()}, the only
-remaining error condition handled from {ExecuteSubscriptionEvent()} are internal
+remaining error condition handled from {ProcessSubscriptionEvent()} are internal
 exceptional errors not described by this specification.
 
-ExecuteSubscriptionEvent(subscription, schema, variableValues, initialValue):
+ProcessSubscriptionEvent(subscription, schema, variableValues, initialValue):
 
 - Let {subscriptionType} be the root Subscription type in {schema}.
 - Assert: {subscriptionType} is an Object type.
 - Let {rootSelectionSet} be the _root selection set_ in {subscription}.
 - Return {ExecuteRootSelectionSet(variableValues, initialValue,
   subscriptionType, rootSelectionSet, "normal")}.
 
-Note: The {ExecuteSubscriptionEvent()} algorithm is intentionally similar to
-{ExecuteQuery()} since this is how each event result is produced.
+Note: The {ProcessSubscriptionEvent()} algorithm is intentionally similar to
+{ProcessQuery()} since this is how each event result is produced.
 
 #### Unsubscribe
 
@@ -637,7 +644,7 @@ A valid GraphQL executor can resolve the four fields in whatever order it chose
 (however of course `birthday` must be resolved before `month`, and `address`
 before `street`).
 
-When executing a mutation, the selections in the top most selection set will be
+When processing a mutation, the selections in the top most selection set will be
 executed in serial order, starting with the first appearing field textually.
 
 When executing a grouped field set serially, the executor must consider each
@@ -785,8 +792,8 @@ Any _request error_ raised as a result of input coercion during
 {CoerceArgumentValues()} should be treated instead as an _execution error_.
 
 Note: Variable values are not coerced because they are expected to be coerced
-before executing the operation in {CoerceVariableValues()}, and valid operations
-must only allow usage of variables of appropriate types.
+before processing the operation in {CoerceVariableValues()}, and valid
+operations must only allow usage of variables of appropriate types.
 
 ### Value Resolution