Merge branch 'master' into chang/avoid-duplicate-directives-redo

.circleci/config.yml

@@ -79,20 +79,10 @@ jobs:
       # (speed) --ignore-scripts to skip unnecessary Lerna build during linting.
       - run: npm install --ignore-scripts
       - run: npm run lint
-  Docs:
-    docker: [{ image: 'circleci/node:8' }]
-    steps:
-      # (speed) Intentionally omitted, unnecessary, run_install_desired_npm.
-      - checkout
-      - restore_cache:
-          key: dependency-cache-{{ checksum "./docs/package.json" }}
-      # (speed) Ignore scripts to skip the Lerna build stuff for linting.
-      - run: npm install-test --prefix ./docs
-      - save_cache:
-          key: dependency-cache-{{ checksum "./docs/package.json" }}
-          paths:
-            - ./docs/node_modules
 
+# XXX We used to use this filter to only run a "Docs" job on docs branches.
+#     Now we use it to disable all jobs. It's unclear if there's a simpler way
+#     to do this!
 ignore_doc_branches: &ignore_doc_branches
   filters:
     branches:
@@ -111,4 +101,3 @@ workflows:
           <<: *ignore_doc_branches
       - Linting:
           <<: *ignore_doc_branches
-      - Docs

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+### vNext
+
+- `apollo-gateway`: Pass `context` through to the `graphql` command in `LocalGraphQLDatasource` `process` method [PR #2821](https://github.com/apollographql/apollo-server/pull/2821)
+- `apollo-gateway`: Fix gateway not sending needed variables for subqueries not at the root level [PR #2867](https://github.com/apollographql/apollo-server/pull/2867)
+- `apollo-federation`: Allow matching enums/scalars in separate services and validate that enums have matching values [PR #2829](https://github.com/apollographql/apollo-server/pull/2829).
+- `apollo-federation`: Strip `@external` fields from interface extensions [PR #2848](https://github.com/apollographql/apollo-server/pull/2848)
+- `apollo-federation`: Add support for list type keys in federation. [PR #2841](https://github.com/apollographql/apollo-server/pull/2841)
+- `apollo-federation`: Deduplicate variable definitions for subqueries [PR #2840](https://github.com/apollographql/apollo-server/pull/2840)
+- `apollo-federation`: Preserve docstrings in SDL of federated services. [PR #2830](https://github.com/apollographql/apollo-server/pull/2830)
+- `apollo-engine-reporting`: Set `forbiddenOperation` and `registeredOperation` later in the request lifecycle [PR #2828](https://github.com/apollographql/apollo-server/pull/2828)
+- `apollo-server-core`: Add queryHash to GraphQLExecutor for federation [PR #2822](https://github.com/apollographql/apollo-server/pull/2822)
+- `apollo-server-core`: fix setting `engine: false` should ignore `ENGINE_API_KEY` in environment variable [PR #2850](https://github.com/apollographql/apollo-server/pull/2850) (a regression introduced in 2.6.0)
+
+### v2.6.2
+
+- `apollo-engine-reporting-protobuf`: Update protobuff to include `forbiddenOperations` and `registeredOperations` [PR #2768](https://github.com/apollographql/apollo-server/pull/2768)
+- `apollo-server-core`: Add `forbiddenOperation` and `registeredOperation` to `GraphQLRequestMetrics` type [PR #2768](https://github.com/apollographql/apollo-server/pull/2768)
+- `apollo-engine-reporting`: Set `forbiddenOperation` and `registeredOperation` on trace if the field is true on `requestContext.metrics` [PR #2768](https://github.com/apollographql/apollo-server/pull/2768)
+- `apollo-server-lambda`: Remove Object.fromEntries usage [PR #2787](https://github.com/apollographql/apollo-server/pull/2787)
+
 ### v2.6.1
 
 - Revert: Don't add `cacheControl` directive if one has already been defined. Presently, although the TypeScript don't suggest it, passing a `String` as `typeDefs` to `ApolloServer` is supported and this would be a breaking change for non-TypeScript users. [PR #2428](https://github.com/apollographql/apollo-server/pull/2428)

docs/package.json

@@ -5,7 +5,7 @@
     "serve": "gatsby serve"
   },
   "dependencies": {
-    "gatsby": "2.8.2",
-    "gatsby-theme-apollo-docs": "1.0.2"
+    "gatsby": "2.10.0",
+    "gatsby-theme-apollo-docs": "1.0.11"
   }
 }

docs/source/api/apollo-federation.mdx

@@ -11,7 +11,7 @@ The `@apollo/federation` has one export for intended public use, the `buildFeder
 
 * `modules`: `GraphQLSchemaModule[]` _(required)_
 
-    An array of schema modules made up of typeDefs and resolvers
+    An array of schema modules made up of typeDefs and resolvers.
 
 #### Usage
 
@@ -47,7 +47,7 @@ const server = new ApolloServer({
 
 ## `__resolveReference`
 
-Though not an export from `@apollo/federation`, using the `buildFederatedSchema` function allows a resovler map to define a new special field called `__resolveReference` for each type that is an entity. This function is called whenever an entity is requested as part of the fufilling a query plan. `__resolveReference` is called with the following parameters:
+Though not an export from `@apollo/federation`, using the `buildFederatedSchema` function allows a resolver map to define a new special field called `__resolveReference` for each type that is an entity. This function is called whenever an entity is requested as part of the fufilling a query plan. `__resolveReference` is called with the following parameters:
 
 #### Parameters
 

docs/source/api/apollo-gateway.mdx

@@ -18,7 +18,7 @@ The core of the federated gateway implementation. For an example, see the ["impl
 
   * `serviceList`: `ServiceDefinition[]` _(required)_
 
-    An array of service definitions. A service definition contains the `name` and `url` for a federated service.
+    An array of service definitions. A service definition contains the `name` and `url` for a federated service. The name is an arbitrary unique string and is primarily used for query planner output, error messages, logging, and the like.
 
     ```js{3-6}
     const gateway = new ApolloGateway({
@@ -52,7 +52,7 @@ The core of the federated gateway implementation. For an example, see the ["impl
 
   * `debug`: `Boolean`
 
-    With debug enabled, the server will log startup errors as well as query plans during incoming requests.
+    With debug enabled, the server will log startup messages as well as query plans during incoming requests.
 
 ### `ApolloGateway.load()`: `Promise<{ schema: GraphQLSchema, exector: GraphQLExecutor }>`
 

docs/source/deployment/azure-functions.md

@@ -205,13 +205,13 @@ Note: When GraphQL Playground starts, It won't have the correct URL containing t
 
 ![Apollo server running on azure with error](../images/deployment/azure-functions/apollo-server-on-azure.png)
 
-We just need to put the full URL that includes the security `code` in the Playground url box. The background polling should refresh the screen momentarily. Click the **Schema** button to see if the docs are loaded correctly as the image below.
+We just need to put the full URL that includes the security `code` in the Playground url box. The background polling should refresh the screen momentarily. Click the **Schema** button to see if the docs are loaded correctly as shown in the image below.
 
 ![Apollo server running on azure with success](../images/deployment/azure-functions/apollo-server-on-azure-sucess.png)
 
 ### Cleaning Up
 
-After complete this tutorial, you can delete all resources at your Azure platform by removing the **az group**. We can delete manually each resource using the following commands:
+After completing this tutorial, you can delete all the resources you created during this example from your Azure account by removing the Azure Resource Group called **apollo-examples** with the **az group** commmand. We can manually delete each resource using the following commands:
 
 ```shell
 az functionapp delete \

docs/source/deployment/netlify.md

@@ -90,10 +90,7 @@ exports.handler = server.createHandler();
 
 Now, make sure you've run `npm run start:lambda`, and navigate to `localhost:9000/graphql` in your browser. You should see GraphQL Playground, where you can run queries against your API!
 
-<div style="text-align:center">
 ![Local GraphQL Server](../images/graphql.png)
-<br></br>
-</div>
 
 If you can see GraphQL Playground and run a simple query, you've done everything properly. Now, let's add Apollo Client to the frontend.
 
@@ -135,17 +132,11 @@ Check the repository to make sure the code showed up.
 
 [Sign up for a Netlify account](https://app.netlify.com/) if you don’t have one yet. Then, make a new site, and select the right repository:
 
-<div style="text-align:center">
 ![Select Repo on Netlify](../images/selectrep.png)
-<br></br>
-</div>
 
 The starter kit came with a `netlify.toml` configuration file, so we don’t have to change any settings in the UI. Just continue to the deploy step right away.
 
-<div style="text-align:center">
 ![Site deploy in progress](../images/sitedeployinprogress.png)
-<br></br>
-</div>
 
 Wait for it to deploy, and in the meanwhile you can set a custom name for your app. Once it’s done, you’re live!
 

docs/source/features/caching.md

@@ -144,4 +144,4 @@ The plugin allows you to define a few more hooks to affect cache behavior for a
 - `shouldReadFromCache`: if this hook returns false, the plugin will not read responses from the cache.
 - `shouldWriteToCache`: if this hook returns false, the plugin will not write responses to the cache.
 
-In addition to the [`Cache-Control` HTTP header](#serving-http-cache-headers), the response cache plugin will also set the `Age` HTTP header to the number of seconds the value has bee sitting in the cache.
+In addition to the [`Cache-Control` HTTP header](#serving-http-cache-headers), the response cache plugin will also set the `Age` HTTP header to the number of seconds the value has been sitting in the cache.

docs/source/features/errors.md

@@ -269,5 +269,5 @@ const server = new ApolloServer({
 In this case, the example error used above would be reported in Apollo Engine as:
 
 ```
-The x-api-key:REDACTED doesn't have sufficient privileges.
+The REDACTED doesn't have sufficient privileges.
 ```

docs/source/features/unions-interfaces.md

@@ -1,6 +1,6 @@
 ---
 title: Unions and interfaces
-description: How to write add unions and interfaces to a schema
+description: How to add unions and interfaces to a schema
 ---
 
 Unions and interfaces are great when you have fields that are in common between two types.

docs/source/federation/advanced-features.md

@@ -54,7 +54,7 @@ type Organization {
 }
 ```
 
-> Note that although the fields argument is parsed as a selection set, some restrictions apply to make the result suitable as a key. For example, fields shouldn't return lists.
+> Note that although the fields argument is parsed as a selection set, some restrictions apply to make the result suitable as a key. For example, fields shouldn't return unions or interfaces.
 
 ## Computed fields
 

docs/source/federation/core-concepts.md

@@ -164,3 +164,49 @@ extend type Query {
 ```
 
 There is no need to explictly define `Query` or `Mutation` base types anywhere; Apollo automatically handles this for you.
+
+## Sharing Types
+
+Sometimes, Enum or Scalar types are needed in multiple services. Rather than having a single service "own" those types, all services that use them are expected to share ownership of those types.
+
+Defining the same Enum or Scalar across services is supported **as long as the definitions are all identical**.
+
+For Enum types, all values must match across services. **Even if a service doesn't use all values in an Enum, they still must be defined in the schema**. Failure to include all enum values in all services that use the Enum will result in a validation error when building the federated schema.
+
+For scalar values, it's important that services **share the same serialization and parsing logic**, since there is no way to validate that logic from the schema level by federation tooling.
+
+In the following example, the Product and User services both use the same ProductCategory enum and Date scalar.
+
+```graphql
+# Product Service
+scalar Date
+
+type Product @key(fields: "sku"){
+  sku: ID!
+  category: ProductCategory
+  dateCreated: Date
+}
+
+enum ProductCategory {
+  FURNITURE
+  BOOK
+  DIGITAL_DOWNLOAD
+}
+
+# User Service
+scalar Date
+
+type User @key(fields: "id"){
+  id: ID!
+  dateCreated: Date
+  favoriteCategory: ProductCategory
+}
+
+enum ProductCategory {
+  FURNITURE
+  BOOK
+  DIGITAL_DOWNLOAD
+}
+```
+
+

docs/source/federation/federation-spec.md

@@ -8,9 +8,9 @@ description: For implementing federation in other languages
 To make a GraphQL service federation capable, it needs the following:
 
 * Implementation of the federation schema specification
+* Support for fetching service capabilities
 * Implementation of stub type generation for references
 * Implementation of request resolving for entities.
-* Support for fetching service capabilities
 
 ## Federation schema specification
 
@@ -36,12 +36,13 @@ directive @external on FIELD_DEFINITION
 directive @requires(fields: _FieldSet!) on FIELD_DEFINITION
 directive @provides(fields: _FieldSet!) on FIELD_DEFINITION
 directive @key(fields: _FieldSet!) on OBJECT
+directive @key(fields: _FieldSet!) on INTERFACE
 
 # this is an optional directive discussed below
 directive @extends on OBJECT
 ```
 
-For more information on these additions, see the [glossary](#schema-modifications-glossary)
+For more information on these additions, see the [glossary](#schema-modifications-glossary).
 
 ## Fetch service capabilities
 
@@ -85,7 +86,7 @@ Execution of a federated graph requires being able to "enter" into a service at
 * Make each entity in the schema part of the `_Entity` union
 * Implement the `_entities` field on the query root
 
-To implement the `_Entity` union, each type annotated with `@key` should be added to the `_Entity` union. If no types are annotated with the key directive, then the `_Entity` union should be removed from the schema. For example, given the following partial schema:
+To implement the `_Entity` union, each type annotated with `@key` should be added to the `_Entity` union. If no types are annotated with the key directive, then the `_Entity` union and `Query._entities` field should be removed from the schema. For example, given the following partial schema:
 
 ```graphql
 type Review @key(fields: "id") {
@@ -227,9 +228,10 @@ A new field must be added to the query root called `_entities`. This field must
 
 ```graphql
 directive @key(fields: _FieldSet!) on OBJECT
+directive @key(fields: _FieldSet!) on INTERFACE
 ```
 
-The `@key` directive is used to indicate a combination of fields that can be used to uniquely identify and fetch an object.
+The `@key` directive is used to indicate a combination of fields that can be used to uniquely identify and fetch an object or interface.
 
 ```graphql
 type Product @key(fields: "upc") {

docs/source/federation/implementing.md

@@ -46,7 +46,7 @@ const server = new ApolloServer({
 });
 ```
 
-If you're already familiar with [setting up an Apollo Server](https://www.apollographql.com/docs/apollo-server/essentials/server#creating), this should look pretty familiar. If not, we recommend you first take a moment to get comfortable with this topic before jumping in to federation.
+If you're already familiar with [setting up an Apollo Server](/essentials/server/#creating-a-server), this should look pretty familiar. If not, we recommend you first take a moment to get comfortable with this topic before jumping in to federation.
 
 Now, let's see what this looks like as a federated service:
 
@@ -125,13 +125,11 @@ const gateway = new ApolloGateway({
 })();
 ```
 
-In this example, we provide two options to the `ApolloGateway` constructor:
-* The `serviceList`, which provides a name and endpoint for each of the federated services.
-* The `debug` flag, which provides some additional logging around gateway startup and query execution. This is useful for troubleshooting, as well as for viewing query plans for incoming requests.
+In this example, we provide the `serviceList` option to the `ApolloGateway` constructor, which provides a name and endpoint for each of the federated services. The name (an arbitrary string) is primarily used for query planner output, error messages, and logging.
 
-On startup, the gateway will fetch the service capabilities from the running servers and form an overall composed graph. It will accept incoming request and create query plans to the underlying services in the service list.
+On startup, the gateway will fetch the service capabilities from the running servers and form an overall composed graph. It will accept incoming requests and create query plans which query the underlying services in the service list.
 
-> If there are any composition errors, the `gateway.load()` promise will be rejected with a list of [validation errors](/federation/errors/)
+> If there are any composition errors, the `gateway.load()` promise will be rejected with a list of [validation errors](/federation/errors/).
 
 #### Gateway initialization
 The call to `gateway.load()` returns a `Promise` which resolves to a `schema` and `executor`. These are intended to be passed into the constructor of `ApolloServer`.
@@ -140,7 +138,7 @@ The call to `gateway.load()` returns a `Promise` which resolves to a `schema` an
 
 ## Inspecting query plans
 
-When the gateway receives a new query, it generates a query plan that defines the sequence of requests the gateway will send to the necessary downstream services. Inspecting a query plan can be a helpful tool in understanding the gateway and exploring how directives like `@requires` and `@provides` can help optimize query plans. To make it easy to access query plans, the `@apollo/gateway` package includes a build of GraphQL Playground that adds a query plan inspector.
+When the gateway receives a new query, it generates a query plan that defines the sequence of requests the gateway will send to the necessary downstream services. Inspecting a query plan can be a helpful tool in understanding the gateway and exploring how directives like [`@requires`](/federation/advanced-features/#computed-fields) and [`@provides`](/federation/advanced-features/#using-denormalized-data) can help optimize query plans. To make it easy to access query plans, the `@apollo/gateway` package includes a build of GraphQL Playground that adds a query plan inspector.
 
 
 ![playground](../images/playground.png)

docs/source/whats-new.md

@@ -48,7 +48,7 @@ This is just the beginning. We have published a [roadmap](https://github.com/apo
 
 ### Automatic Persisted Queries
 
-A persisted query is an ID or hash that can be sent to the server in place of the GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times. Apollo Server enables persisted queries without additional server configuration, using an in-memory LRU cache to store the mapping between hash and query string. The persisted query cache can be configured as shown in the following code snippet. To enable persisted queries on the client, follow the [Performance Guide](https://www.apollographql.com/docs/guides/performance.html#Automatic-Persisted-Queries).
+A persisted query is an ID or hash that can be sent to the server in place of the GraphQL query string. This smaller signature reduces bandwidth utilization and speeds up client loading times. Apollo Server enables persisted queries without additional server configuration, using an in-memory LRU cache to store the mapping between hash and query string. The persisted query cache can be configured as shown in the following code snippet. To enable persisted queries on the client, follow the [Performance Guide](https://www.apollographql.com/docs/apollo-server/features/apq/).
 
 ```js{7-12}
 const { ApolloServer } = require('apollo-server');
@@ -70,7 +70,7 @@ server.listen().then(({ url }) => {
 });
 ```
 
-For more information on automatic persisted queries, check the [APQ section of the performance guide](https://www.apollographql.com/docs/guides/performance.html#automatic-persisted-queries).
+For more information on automatic persisted queries, check the [APQ section of the performance guide](https://www.apollographql.com/docs/apollo-server/features/apq/).
 
 ### CDN integration