Feat: Adds server.create() (#606)

docs/getting-started.md

@@ -61,6 +61,25 @@ Available unleash options include:
 - **eventHook** (`function(event, data)`) - If provided, this function will be invoked whenever a feature is mutated. The possible values for `event` are `'feature-created'`, `'feature-updated'`, `'feature-archived'`, `'feature-revived'`. The `data` argument contains information about the mutation. Its fields are `type` (string) - the event type (same as `event`); `createdBy` (string) - the user who performed the mutation; `data` - the contents of the change. The contents in `data` differs based on the event type; For `'feature-archived'` and `'feature-revived'`, the only field will be `name` - the name of the feature. For `'feature-created'` and `'feature-updated'` the data follows a schema defined in the code [here](https://github.com/Unleash/unleash/blob/master/lib/routes/admin-api/feature-schema.js#L38-L59). See an example [here](./guides/feautre-updates-to-slack.md).
 - **baseUriPath** (string) - use to register a base path for all routes on the application. For example `/my/unleash/base` (note the starting /). Defaults to `/`. Can also be configured through the environment variable `BASE_URI_PATH`.
 
+#### Disabling Auto-Start
+
+If you're using unleash as part of a larger express app, you can disable the automatic server start by calling `server.create`. It takes the same options as `sevrer.start`, but will not begin listening for connections.
+
+```js
+const unleash = require('unleash-server');
+// ... const app = express();
+
+unleash
+  .create({
+    databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash',
+    port: 4242,
+  })
+  .then(result => {
+    app.use(result.app);
+    console.log(`Unleash app generated and attached to parent application`);
+  });
+```
+
 ### 3. Docker
 
 You can also use the [hosted docker image](https://hub.docker.com/r/unleashorg/unleash-server/) to start the Unleash server

examples/express-parent-app.js

@@ -0,0 +1,17 @@
+/* eslint-disable import/no-unresolved */
+
+'use strict';
+
+const express = require('express');
+const unleash = require('../lib/server-impl.js');
+
+const app = express();
+unleash
+    .create({
+        databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash',
+        baseUriPath: '/unleash',
+    })
+    .then(unl => {
+        app.use(unl.app); // automatically mounts to baseUriPath
+        app.listen(process.env.PORT);
+    });

lib/options.js

@@ -51,6 +51,7 @@ function defaultOptions() {
         getLogger: defaultLogProvider,
         customContextFields: [],
         disableDBMigration: false,
+        start: true,
     };
 }
 

lib/server-impl.js

@@ -53,22 +53,26 @@ async function createApp(options) {
         });
     }
 
-    const server = app.listen(options.listen, () =>
-        logger.info('Unleash has started.', server.address()),
-    );
-
     return new Promise((resolve, reject) => {
-        server.on('listening', () =>
-            resolve({
-                app,
-                config,
-                stores,
-                server,
-                eventBus,
-                stateService,
-            }),
-        );
-        server.on('error', reject);
+        const payload = {
+            app,
+            config,
+            stores,
+            eventBus,
+            stateService,
+        };
+
+        if (options.start) {
+            const server = app.listen(options.listen, () =>
+                logger.info('Unleash has started.', server.address()),
+            );
+            server.on('listening', () => {
+                resolve({ ...payload, server });
+            });
+            server.on('error', reject);
+        } else {
+            resolve({ ...payload });
+        }
     });
 }
 
@@ -90,8 +94,13 @@ async function start(opts) {
     return createApp(options);
 }
 
+async function create(opts) {
+    return start({ ...opts, start: false });
+}
+
 module.exports = {
     start,
+    create,
     User,
     AuthenticationRequired,
     permissions,

lib/server-impl.test.js

@@ -82,3 +82,20 @@ test('should call eventHook', async t => {
     eventStore.emit('feature-created', {});
     t.true(called === 1);
 });
+
+test('should auto-create server on start()', async t => {
+    const { server } = await serverImpl.start({
+        port: 0,
+        getLogger,
+        start: true,
+    });
+    t.false(typeof server === 'undefined');
+});
+
+test('should not create a server using create()', async t => {
+    const { server } = await serverImpl.create({
+        port: 0,
+        getLogger,
+    });
+    t.true(typeof server === 'undefined');
+});