Subscription support for GraphiQL (#687)

* FEAT: add subscription support
* Added http-test for subscription scenario
* add sample implementation with subscription support
* move subscription test case within graphiql section
* fixed linter error by adding null check

Co-authored-by: jliu670 <[email protected]>
Co-authored-by: junmin_liu <[email protected]>

Author: 3 people

README.md

@@ -68,6 +68,54 @@ app.get(
 app.listen(4000);
 ```
 
+## Setup with Subscription Support
+
+```js
+const express = require('express');
+const { graphqlHTTP } = require('express-graphql');
+
+const typeDefs = require('./schema');
+const resolvers = require('./resolvers');
+const { makeExecutableSchema } = require('graphql-tools');
+const schema = makeExecutableSchema({
+  typeDefs: typeDefs,
+  resolvers: resolvers,
+});
+
+const { execute, subscribe } = require('graphql');
+const { createServer } = require('http');
+const { SubscriptionServer } = require('subscriptions-transport-ws');
+
+const PORT = 4000;
+
+var app = express();
+
+app.use(
+  '/graphql',
+  graphqlHTTP({
+    schema: schema,
+    graphiql: { subscriptionEndpoint: `ws://localhost:${PORT}/subscriptions` },
+  }),
+);
+
+const ws = createServer(app);
+
+ws.listen(PORT, () => {
+  // Set up the WebSocket for handling GraphQL subscriptions.
+  new SubscriptionServer(
+    {
+      execute,
+      subscribe,
+      schema,
+    },
+    {
+      server: ws,
+      path: '/subscriptions',
+    },
+  );
+});
+```
+
 ## Options
 
 The `graphqlHTTP` function accepts the following options:
@@ -88,6 +136,8 @@ The `graphqlHTTP` function accepts the following options:
   - **`headerEditorEnabled`**: An optional boolean which enables the header editor when true.
     Defaults to false.
 
+  - **`subscriptionEndpoint`**: An optional GraphQL string contains the WebSocket server url for subscription.
+
 - **`rootValue`**: A value to pass as the `rootValue` to the `graphql()`
   function from [`GraphQL.js/src/execute.js`](https://github.com/graphql/graphql-js/blob/master/src/execution/execute.js#L119).
 

package-lock.json

@@ -84,6 +84,7 @@
     "eslint-plugin-node": "11.1.0",
     "express": "4.17.1",
     "graphiql": "1.0.6",
+    "graphiql-subscriptions-fetcher": "0.0.2",
     "graphql": "15.4.0",
     "mocha": "8.2.1",
     "multer": "1.4.2",
@@ -94,6 +95,7 @@
     "react-dom": "16.14.0",
     "restify": "8.5.1",
     "sinon": "9.2.1",
+    "subscriptions-transport-ws": "0.5.4",
     "supertest": "6.0.1",
     "ts-node": "9.0.0",
     "typescript": "4.1.2",

package.json

@@ -1988,6 +1988,33 @@ function runTests(server: Server) {
       expect(response.type).to.equal('application/json');
       expect(response.text).to.equal('{"data":{"test":"Hello World"}}');
     });
+
+    it('contains subscriptionEndpoint within GraphiQL', async () => {
+      const app = server();
+
+      app.get(
+        urlString(),
+        graphqlHTTP({
+          schema: TestSchema,
+          graphiql: { subscriptionEndpoint: 'ws://localhost' },
+        }),
+      );
+
+      const response = await app
+        .request()
+        .get(urlString())
+        .set('Accept', 'text/html');
+
+      expect(response.status).to.equal(200);
+      expect(response.type).to.equal('text/html');
+      // should contain the function to make fetcher for subscription or non-subscription
+      expect(response.text).to.include('makeFetcher');
+      // should contain subscriptions-transport-ws browser client
+      expect(response.text).to.include('SubscriptionsTransportWs');
+
+      // should contain the subscriptionEndpoint url
+      expect(response.text).to.include('ws:\\/\\/localhost');
+    });
   });
 
   describe('Custom validate function', () => {