Merge branch 'server-2.0/caching' into server-2.0/caching-connectors

.circleci/config.yml

@@ -1,13 +1,20 @@
 version: 2
 
+#
 # Reusable Snippets!
 #
 # These are re-used by the various tests below, to avoid repetition.
 #
 run_install_desired_npm: &run_install_desired_npm
   run:
-    name: Install npm@6
-    command: sudo npm install -g npm@6
+    # Due to a bug, npm upgrades from the version of npm that ships with
+    # Node.js 6 (npm v3.10.10) go poorly and generally causes other problems
+    # with the environment.  Since yarn is already available here we can just
+    # use that to work-around the issue.  It's possible that npm cleanup might
+    # prevent this from being necessary, but this installation can be switched
+    # to use `npm` (rather than `yarn`) once Node 6 is no longer tested below.
+    name: Install npm@5, but with yarn.
+    command: sudo yarn global add npm@5
 
 # These are the steps used for each version of Node which we're testing
 # against.  Thanks to YAMLs inability to merge arrays (though it is able
@@ -29,6 +36,10 @@ jobs:
   # Platform tests, each with the same tests but different platform or version.
   # The docker tag represents the Node.js version and the full list is available
   # at https://hub.docker.com/r/circleci/node/.
+  Node.js 6:
+    docker: [ { image: 'circleci/node:6' } ]
+    <<: *common_test_steps
+
   Node.js 8:
     docker: [ { image: 'circleci/node:8' } ]
     <<: *common_test_steps
@@ -64,6 +75,8 @@ workflows:
   version: 2
   Build and Test:
     jobs:
+      - Node.js 6:
+          <<: *ignore_doc_branches
       - Node.js 8:
           <<: *ignore_doc_branches
       - Node.js 10:

README.md

@@ -1,11 +1,11 @@
-# GraphQL Server for Express, Connect, Hapi, Koa, and more
-
-Also supports: Restify, Micro, Azure Functions, AWS Lambda and Adonis Framework
+# GraphQL Server for Express, Connect, Hapi, Cloudflare workers, and more
 
 [![npm version](https://badge.fury.io/js/apollo-server-core.svg)](https://badge.fury.io/js/apollo-server-core)
 [![Build Status](https://circleci.com/gh/apollographql/apollo-cache-control-js.svg?style=svg)](https://circleci.com/gh/apollographql/apollo-cache-control-js)
 [![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](https://www.apollographql.com/#slack)
 
+FIXME update README for 2.x; refer to 1.x branch for currently unsupported web frameworks and encourage community to help port ApolloServer to other frameworks.
+
 Apollo Server is a community-maintained open-source GraphQL server. It works with pretty much all Node.js HTTP server frameworks, and we're happy to take PRs for more! Apollo Server works with any GraphQL schema built with [GraphQL.js](https://github.com/graphql/graphql-js), so you can build your schema with that directly or with a convenience library such as [graphql-tools](https://www.apollographql.com/docs/graphql-tools/).
 
 ## Documentation

docs/_config.yml

@@ -35,11 +35,10 @@ sidebar_categories:
     - api/apollo-server
     - title: graphql-subscriptions
       href: https://www.apollographql.com/docs/graphql-subscriptions
-    - title: apollo-engine
-      href: https://www.apollographql.com/docs/engine/setup-node.html#api
     - api/graphql-tools
   Migration:
     - migration-two-dot
+    - migration-engine
 
 github_repo: apollographql/apollo-server
 content_root: docs/source

docs/source/api/apollo-server.md

@@ -69,61 +69,45 @@ new ApolloServer({
 
   An executable GraphQL schema that will override the `typeDefs` and `resolvers` provided
 
-#### Returns
-
-`ApolloServer`
-
-### `listen(options)`: `Promise`
-
-#### Parameters
-
-* `options`: <`Object`>
-
-  * `http`: <`Object`>
 
-    All parameters which are supported by Node.js' [`net.Server.listen`](https://nodejs.org/api/net.html#net_server_listen_options_callback) method are supported, including:
+* `subscriptions`: <`Object`> | <`String`> | false
 
-    * `port`: <`String`> | <`Number`>
-    * `path`: <`String`>
-    * `backlog`: <`Number`>
-    * `exclusive`: <`Boolean`>
+  String defining the path for subscriptions or an Object to customize the subscriptions server. Set to false to disable subscriptions
 
-    or
+  * `path`: <`String`>
+  * `keepAlive`: <`Number`>
+  * `onConnect`: <`Function`>
+  * `onDisconnect`: <`Function`>
 
-    * `handler`: <`Object`>
-    * `backlog`: <`Number`>
-
-  Engine launcher options
-
-  * `engineLauncherOptions` : [<`Object`>](https://www.apollographql.com/docs/engine/setup-node.html#api-engine.listen)
-  * `engineProxy`: [<`Object`>](https://www.apollographql.com/docs/engine/proxy-config.html)
+#### Returns
 
-  WebSocket options
+`ApolloServer`
 
-  * `subscriptions`: <`Object`> | <`String`> | false
+### `ApolloServer.listen(options)`: `Promise`
 
-    String defining the path for subscriptions or an Object to customize the subscriptions server. Set to false to disable subscriptions
+#### Parameters
 
-    * `path`: <`String`>
-    * `keepAlive`: <`Number`>
-    * `onConnect`: <`Function`>
-    * `onDisconnect`: <`Function`>
+In `apollo-server`, the listen call starts the subscription server and passes the arguments directly to an http server Node.js' [`net.Server.listen`](https://nodejs.org/api/net.html#net_server_listen) method are supported.
 
 #### Returns
 
-`Promise`
+`Promise` that resolves to an object that contains:
+
+  * `url`: <`String`>
+  * `subscriptionsPath`: <`String`>
+  * `server`: <[`http.Server`](https://nodejs.org/api/http.html#http_class_http_server)>
 
-## registerServer
+## ApolloServer.applyMiddleware
 
-The `registerServer` method is from `apollo-server-express`. Middleware registration has been greatly simplified with this new method.
+The `applyMiddleware` method is provided by the `apollo-server-{integration}` packages that use middleware, such as hapi and express. This function connects ApolloServer to a specific framework.
 
 ### Parameters
 
 * `options`: <`Object`>
 
   * `app`: <`HttpServer`> _(required)_
 
-    Pass the handle to your nexpress server here.
+    Pass an instance of the server integration here.
 
   * `server`: <`ApolloServer`> _(required)_
 
@@ -133,17 +117,20 @@ The `registerServer` method is from `apollo-server-express`. Middleware registra
 
     Specify a custom path. It defaults to `/graphql` if no path is specified.
 
-  * `cors`: <`Object`>
+  * `cors`: <`Object` | `boolean`> ([express](https://github.com/expressjs/cors#cors), [hapi](https://hapijs.com/api#-routeoptionscors))
+
+    Pass the integration-specific cors options. False removes the cors middleware and true uses the defaults.
+
+  * `bodyParser`: <`Object` | `boolean`> ([express](https://github.com/expressjs/body-parser#body-parser))
 
-    Pass the cors options.
+    Pass the body-parser options. False removes the body parser middleware and true uses the defaults.
 
 ### Usage
 
-The `registerServer` method from `apollo-server-express` allows you to easily register your middleware as shown in the example below:
+The `applyMiddleware` method from `apollo-server-express` registration of middleware as shown in the example below:
 
 ```js
-const { ApolloServer } = require('apollo-server');
-const { registerServer } = require('apollo-server-express');
+const { ApolloServer } = require('apollo-server-express');
 const { typeDefs, resolvers } = require('./schema');
 
 const server = new ApolloServer({
@@ -155,7 +142,7 @@ const server = new ApolloServer({
 // Additional middleware can be mounted at this point to run before Apollo.
 app.use('*', jwtCheck, requireAuth, checkScope);
 
-registerServer({ server, app, path: '/specialUrl' }); // app is from an existing express app. Mount Apollo middleware here. If no path is specified, it defaults to `/graphql`.
+server.applyMiddleware({ app, path: '/specialUrl' }); // app is from an existing express app. Mount Apollo middleware here. If no path is specified, it defaults to `/graphql`.
 ```
 
 ## `gql`
@@ -166,7 +153,7 @@ In the case of GraphQL, the `gql` tag is used to surround GraphQL operation and
 
 ### Usage
 
-Import the `gql` template literal tag into the current context from the `apollo-server` module:
+Import the `gql` template literal tag into the current context from the `apollo-server` or `apollo-server-{integration}` modules:
 
 ```js
 const { gql } = require('apollo-server');

docs/source/best-practices/caching.md

@@ -7,7 +7,7 @@ One of the best ways we can speed up our application is to implement caching int
 
 <h2 id="whole-query">Whole query caching</h2>
 
-GraphQL operations on a client are best when they are statically defined and used in an application. When this is the case, often times there will be operations that could easily be cached as a full result of the the request. We call this *whole query caching* and it is incredibly easy to implement with Apollo Engine. Unlike custom REST endpoints, using Apollo Server allows us to define the cacheability of our resources and dynamically calculate the best possible cache timing for any given operation. If Apollo Server is configured to use Apollo Engine, caching is setup automatically with default configuration.
+GraphQL operations on a client are best when they are statically defined and used in an application. When this is the case, often times there will be operations that could easily be cached as a full result of the the request. We call this *whole query caching* and it is incredibly easy to implement with Apollo Server. Unlike custom REST endpoints, using Apollo Server allows us to define the cacheability of our resources and dynamically calculate the best possible cache timing for any given operation.
 
 - For more information about setting up Apollo Engine with Apollo Server, [read this guide]()
 - For more information about setting up whole query caching with Apollo Engine, [read this guide](https://www.apollographql.com/docs/engine/caching.html)

docs/source/essentials/data.md

@@ -239,4 +239,4 @@ GraphQL clients, like [Apollo Client](https://www.apollographql.com/docs/react/)
 }
 ```
 
-This functionality is also supported by tools like GraphQL Playground and GraphiQL.
+This functionality is also supported by tools like GraphQL Playground.

docs/source/essentials/schema.md

@@ -234,7 +234,7 @@ type MyObjectType {
 }
 ```
 
-This makes SDL-generation even easier since many GraphQL tools (like GraphQL Playground and GraphiQL) auto-complete field names, along with the descriptions, when available.
+This makes SDL-generation even easier since many GraphQL tools (like GraphQL Playground) auto-complete field names, along with the descriptions, when available.
 
 <h3 id="introspection">Introspection</h3>
 

docs/source/essentials/server.md

@@ -115,21 +115,12 @@ Both import methods will use the `apollo-server` module we installed in the prev
 
 <h3 id="middleware">Middleware</h3>
 
-Existing applications generally already have middleware in place and Apollo Server works along with those middleware.
-
-To integrate Apollo Server with an existing server, we will need to import `registerServer` from the appropriate support package.  For example, if the application is already using an Express server, this would import `registerServer` from the `apollo-server-express` module:
-
-```js
-const { registerServer } = require('apollo-server-express');
-```
-
-For existing applications, we'll pass it into the `registerServer` method as `app`.
+Existing applications generally already have middleware in place and Apollo Server works along with those middleware. To integrate with Apollo Server, we'll pass it into the `server.applyMiddleware` method as `app` to add the Apollo Server's middleware.
 
 > The existing application is frequently already named `app`, especially when using Express.  If the application is identified by a different variable, pass the existing variable in place of `app`.
 
 ```js
-const { ApolloServer, gql } = require('apollo-server');
-const { registerServer } = require('apollo-server-express');
+const { ApolloServer, gql } = require('apollo-server-express');
 const { typeDefs, resolvers } = require('./schema');
 
 const server = new ApolloServer({
@@ -138,7 +129,11 @@ const server = new ApolloServer({
   resolvers,
 });
 
-registerServer({ server, app }); // app is from an existing express app
+server.applyMiddleware({ app }); // app is from an existing express app
+
+app.listen({ port: 4000 }, () =>
+  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
+)
 ```
 
 

docs/source/features/apq.md

@@ -75,12 +75,12 @@ The mechanism is based on a lightweight protocol extension between Apollo Client
 <h3 id="Optimized-Path">**Optimized Path**</h3>
 </div>
 
-![Optimized path](../img/persistedQueries.optPath.png)
+![Optimized path](../images/persistedQueries.optPath.png)
 
 <div align="center">
 <h3 id="New-Query-Path">**New Query Path**</h3>
 </div>
 
-![New query path](../img/persistedQueries.newPath.png)
+![New query path](../images/persistedQueries.newPath.png)
 
 

docs/source/features/scalars-enums.md

@@ -215,7 +215,7 @@ server.listen().then(({ url }) => {
 
 <h2 id="enums">Enums</h2>
 
-An Enum is similar to a scalar type, but it can only be one of several values defined in the schema. Enums are most useful in a situation where the user must pick from a prescribed list of options. Additionally enums improve development velocity, since they will auto-complete in tools like GraphiQL.
+An Enum is similar to a scalar type, but it can only be one of several values defined in the schema. Enums are most useful in a situation where the user must pick from a prescribed list of options. Additionally enums improve development velocity, since they will auto-complete in tools like GraphQL Playground.
 
 In the schema language, an enum looks like this:
 

docs/source/getting-started.md

@@ -8,7 +8,7 @@ In this guide, we'll walk you through the process of creating a GraphQL server i
 
 * Have a basic GraphQL server which will work as a foundation for a more complex server.
 * Have a basic understanding of the fundamental GraphQL principles.
-* Be able to send a query to the new GraphQL server and see the response using the GraphiQL user interface.
+* Be able to send a query to the new GraphQL server and see the response using GraphQL Playground.
 
 To be successful, make sure you already have general JavaScript knowledge, a recent version of Node.js installed (6+).