Merge branch 'devel' of https://github.com/arangodb/arangodb into devel

CHANGELOG

@@ -23,6 +23,9 @@ devel
 
 * When disabling Foxx development mode the setup script is now re-run
 
+* Foxx now provides an easy way to directly serve GraphQL requests using the
+  `@arangodb/foxx/graphql` module and the bundled `graphql-sync` dependency
+
 
 v3.0.3 (XXXX-XX-XX)
 -------------------

Documentation/Books/Manual/Foxx/GraphQL.mdpp

@@ -0,0 +1,105 @@
+!CHAPTER Using GraphQL in Foxx
+
+`const createGraphQLRouter = require('@arangodb/foxx/graphql');`
+
+Foxx bundles the [`graphql-sync` module](https://github.com/arangodb/graphql-sync), which is a synchronous wrapper for the official JavaScript GraphQL reference implementation, to allow writing GraphQL schemas directly inside Foxx.
+
+Additionally the `@arangodb/foxx/graphql` lets you create routers for serving GraphQL requests, which closely mimicks the behaviour of the [`express-graphql` module](https://github.com/graphql/express-graphql).
+
+For more information on `graphql-sync` see the [`graphql-js` API reference](http://graphql.org/docs/api-reference-graphql/) (note that `graphql-sync` always uses raw values instead of wrapping them in promises).
+
+For an example of a GraphQL schema in Foxx that resolves fields using the database see [the GraphQL example service](https://github.com/arangodb-foxx/demo-graphql) (also available from the Foxx store).
+
+**Examples**
+
+```js
+const graphql = require('graphql-sync');
+const graphqlSchema = new graphql.GraphQLSchema({
+  // ...
+});
+
+// Mounting a graphql endpoint directly in a service:
+module.context.use('/graphql', createGraphQLRouter({
+  schema: graphqlSchema,
+  graphiql: true
+}));
+
+// Or at the service's root URL:
+module.context.use(createGraphQLRouter({
+  schema: graphqlSchema,
+  graphiql: true
+}));
+
+// Or inside an existing router:
+router.get('/hello', function (req, res) {
+  res.write('Hello world!');
+});
+router.use('/graphql', createGraphQLRouter({
+  schema: graphqlSchema,
+  graphiql: true
+}));
+```
+
+!SECTION Creating a router
+
+`createGraphQLRouter(options): Router`
+
+This returns a new router object with POST and GET routes for serving GraphQL requests.
+
+**Arguments**
+
+* **options**: `object`
+
+  An object with any of the following properties:
+
+  * **schema**: `GraphQLSchema`
+
+    A GraphQL Schema object from `graphql-sync`.
+
+  * **context**: `any` (optional)
+
+    The GraphQL context that will be passed to the `graphql()` function from `graphql-sync` to handle GraphQL queries.
+
+  * **rootValue**: `object` (optional)
+
+    The GraphQL root value that will be passed to the `graphql()` function from `graphql-sync` to handle GraphQL queries.
+
+  * **pretty**: `boolean` (Default: `false`)
+
+    If `true`, JSON responses will be pretty-printed.
+
+  * **formatError**: `Function` (optional)
+
+    A function that will be used to format errors produced by `graphql-sync`. If omitted, the `formatError` function from `graphql-sync` will be used instead.
+
+  * **validationRules**: `Array<any>` (optional)
+
+    Additional validation rules queries must satisfy in addition to those defined in the GraphQL spec.
+
+  * **graphiql**: `boolean` (Default: `false`)
+
+    If `true`, the [GraphiQL](https://github.com/graphql/graphiql) explorer will be served when loaded directly from a browser.
+
+If a GraphQL Schema object is passed instead of an options object it will be interpreted as the *schema* option.
+
+!SECTION Generated routes
+
+The router handles GET and POST requests to its root path and accepts the following parameters, which can be provided either as query parameters or as the POST request body:
+
+* **query**: `string`
+
+  A GraphQL query that will be executed.
+
+* **variables**: `object | string` (optional)
+
+  An object or a string containing a JSON object with runtime values to use for any GraphQL query variables.
+
+* **operationName**: `string` (optional)
+
+  If the provided `query` contains multiple named operations, this specifies which operation should be executed.
+
+* **raw**: `boolean` (Default: `false`)
+
+  Forces a JSON response even if *graphiql* is enabled and the request was made using a browser.
+
+The POST request body can be provided as JSON or as query string using `application/x-www-form-urlencoded`. A request body passed as `application/graphql` will be interpreted as the `query` parameter.

Documentation/Books/Manual/SUMMARY.md

@@ -74,6 +74,7 @@
     * [Middleware](Foxx/Router/Middleware.md)
     * [Request](Foxx/Router/Request.md)
     * [Response](Foxx/Router/Response.md)
+  * [Using GraphQL](Foxx/GraphQL.md)
   * [Sessions middleware](Foxx/Sessions/README.md)
     * [Session storages](Foxx/Sessions/Storages/README.md)
       * [Collection storage](Foxx/Sessions/Storages/Collection.md)

js/server/modules/@arangodb/foxx/graphql.js

@@ -22,14 +22,6 @@
 // / @author Alan Plum
 // //////////////////////////////////////////////////////////////////////////////
 
-// * schema: Object the schema
-// * context: ?mixed graphql context
-// * rootValue: ?Object graphql rootValue
-// * pretty: ?boolean prettier output
-// * formatError: ?Function formatError for graphql errors
-// * validationRules: ?Array<any> additional validation rules???
-// * graphiql: ?boolean enable graphiql
-
 const dd = require('dedent');
 const assert = require('assert');
 const joi = require('joi');