feat(sse): add server-sent events endpoint

Author: shadowgate15

README.md

@@ -39,10 +39,11 @@ The API will start automatically when the Bree constructor is called.
 
 ## Options
 
-| Option |  Type  | Description                                                                                  |
-|:------:|:------:|----------------------------------------------------------------------------------------------|
-|  port  | Number | The port the API will listen on. Default: `62893`                                            |
-|   jwt  | Object | Configurations for JWT. Only option is `secret` which will be the secret used to verify JWT. |
+| Option   | Type     | Description                                                                                    |
+| :------: | :------: | ---------------------------------------------------------------------------------------------- |
+| port     | Number   | The port the API will listen on. Default: `62893`                                              |
+| jwt      | Object   | Configurations for JWT. Only option is `secret` which will be the secret used to verify JWT.   |
+| sse      | Object   | Configurations for SSE. See [koa-sse][] for list of options.                                   |
 
 ## API
 
@@ -62,3 +63,5 @@ Check out the [API Docs](https://documenter.getpostman.com/view/17142435/TzzDLbN
 [yarn]: https://yarnpkg.com/
 
 [Bree]: https://jobscheduler.net/#/
+
+[koa-sse]: https://github.com/yklykl530/koa-sse

api.js

@@ -10,7 +10,7 @@ const ip = require('ip');
 const logger = require('./helpers/logger');
 const apiConfig = require('./config/api');
 
-const api = new API(apiConfig);
+const api = new API(apiConfig());
 
 if (!module.parent) {
   const graceful = new Graceful({
@@ -25,7 +25,7 @@ if (!module.parent) {
       if (process.send) process.send('ready');
       const { port } = api.server.address();
       logger.info(
-        `Lad API server listening on ${port} (LAN: ${ip.address()}:${port})`
+        `Bree API server listening on ${port} (LAN: ${ip.address()}:${port})`
       );
     } catch (error) {
       logger.error(error);

app/controllers/api/v1/index.js

@@ -1,9 +1,10 @@
 const config = require('./config');
 const jobs = require('./jobs');
 const control = require('./control');
+const sse = require('./sse');
 
 const test = (ctx) => {
   ctx.body = { breeExists: Boolean(ctx.bree) };
 };
 
-module.exports = { config, test, jobs, control };
+module.exports = { config, test, jobs, control, sse };

app/controllers/api/v1/sse.js

@@ -0,0 +1,16 @@
+async function connect(ctx) {
+  if (ctx.sse) {
+    // send bree events over sse
+    for (const event of ['worker created', 'worker deleted']) {
+      ctx.bree.on(event, (name) => {
+        ctx.sse.send({ event, data: { name } });
+      });
+    }
+
+    ctx.sse.on('close', () => {
+      ctx.logger.error('SSE closed');
+    });
+  }
+}
+
+module.exports = { connect };

config/api.js

@@ -1,15 +1,54 @@
 const sharedConfig = require('@ladjs/shared-config');
 const jwt = require('koa-jwt');
+const sse = require('koa-sse-stream');
 
 const logger = require('../helpers/logger');
 const routes = require('../routes');
 const config = require('../config');
 
-module.exports = {
-  ...sharedConfig('API'),
-  routes: routes.api,
-  logger,
-  hookBeforeRoutes(app) {
-    app.use(jwt(config.jwt));
-  }
+module.exports = (opts = {}) => {
+  const sseMiddleware = sse({ ...config.sse, ...opts.sse });
+  const jwtMiddleware = jwt({
+    ...config.jwt,
+    ...opts.jwt,
+    getToken(ctx, _) {
+      // pull token off of url if it is the sse endpoint
+      if (ctx.url.indexOf('/v1/sse') === 0) {
+        const splitUrl = ctx.url.split('/');
+
+        if (splitUrl.length === 4) {
+          return splitUrl[3];
+        }
+      }
+
+      return null;
+    }
+  });
+
+  return {
+    ...sharedConfig('API'),
+    port: config.port,
+    ...opts,
+    routes: routes.api,
+    logger,
+    hookBeforeRoutes(app) {
+      app.use((ctx, next) => {
+        // return early if jwt is set to false
+        if (!opts.jwt && typeof opts.jwt === 'boolean') {
+          return next();
+        }
+
+        return jwtMiddleware(ctx, next);
+      });
+
+      app.use((ctx, next) => {
+        // only do this on sse route
+        if (ctx.url.indexOf('/v1/sse') === 0) {
+          return sseMiddleware(ctx, next);
+        }
+
+        return next();
+      });
+    }
+  };
 };

config/index.js

@@ -30,6 +30,12 @@ const config = {
     secret: env.JWT_SECRET
   },
 
+  // sse options
+  sse: {
+    maxClients: 10_000,
+    pingInterval: 60_000
+  },
+
   // store IP address
   // <https://github.com/ladjs/store-ip-address>
   storeIPAddress: {

index.js

@@ -1,5 +1,4 @@
 const API = require('@ladjs/api');
-const jwt = require('koa-jwt');
 
 const api = require('./api');
 const apiConfig = require('./config/api');
@@ -10,17 +9,11 @@ function plugin(opts, Bree) {
   opts = {
     port: config.port,
     jwt: config.jwt,
+    sse: config.sse,
     ...opts
   };
 
-  const api = new API({
-    ...apiConfig,
-    port: opts.port,
-    jwt: opts.jwt,
-    hookBeforeRoutes(app) {
-      app.use(jwt(opts.jwt));
-    }
-  });
+  const api = new API(apiConfig(opts));
 
   const oldInit = Bree.prototype.init;
 

package.json

@@ -34,6 +34,7 @@
     "humanize-string": "^3.0.0",
     "ip": "^1.1.5",
     "koa-jwt": "^4.0.1",
+    "koa-sse-stream": "^0.2.0",
     "lodash": "^4.17.20",
     "markdown-it": "^13.0.1",
     "markdown-it-emoji": "^2.0.0",
@@ -55,6 +56,7 @@
     "eslint-formatter-pretty": "^4.0.0",
     "eslint-plugin-compat": "^4.0.2",
     "eslint-plugin-no-smart-quotes": "^1.1.0",
+    "eventsource": "^2.0.2",
     "fixpack": "^4.0.0",
     "get-port": "^5.1.1",
     "gulp": "^4.0.2",

routes/api/v1/index.js

@@ -29,4 +29,6 @@ router.post('/run/:jobName', api.v1.control.run);
 router.post('/restart', api.v1.control.restart);
 router.post('/restart/:jobName', api.v1.control.restart);
 
+router.get('/sse/:token', api.v1.sse.connect);
+
 module.exports = router;

test/api/v1/index.js

@@ -13,6 +13,7 @@ test.before(async (t) => {
 test('fails when no creds are presented', async (t) => {
   const { api } = t.context;
   const res = await api.get('/v1/test');
+
   t.is(res.status, 401);
 });