feat(smartive): add promise to start and stop function (#188)

BREAKING CHANGE: Closes #171. Closes #172. 
This PR introduces async start and stop functions.
During this change, the optional callbacks are removed since the call
can now be awaited. If no port is given to the start function, a random
one is created and used.

Migration: remove all callbacks and hostnames from the start function
and remove all callbacks from the stop function. They can now be
awaited as normal.

Author: buehler

src/Giuseppe.ts

@@ -22,6 +22,7 @@ import { GiuseppeRoute } from './routes/GiuseppeRoute';
 import { ReturnType } from './routes/ReturnType';
 import { HttpMethod } from './routes/RouteDefinition';
 import { ControllerMetadata } from './utilities/ControllerMetadata';
+import { getRandomPort } from './utilities/RandomPort';
 
 /**
  * Score sort function for route register information. Calculates the sorting score based on segments, url params
@@ -76,6 +77,18 @@ export class Giuseppe {
         return this._server;
     }
 
+    /**
+     * Gets the used port of giuseppe (and the given express app). Returns undefined if the app
+     * is not started yet.
+     *
+     * @readonly
+     * @type {(number | undefined)}
+     * @memberof Giuseppe
+     */
+    public get port(): number | undefined {
+        return this._port;
+    }
+
     /**
      * The express application behind this instance of giuseppe. Someone might want to change the used express instance
      * before calling [start()]{@link Giuseppe#start()}. Also, on this propert you can add other things like
@@ -105,6 +118,8 @@ export class Giuseppe {
     protected _pluginRouteModificators: RouteModificatorConstructor[] | null = null;
     protected _pluginParameters: ParameterDefinitionConstructor[] | null = null;
 
+    private _port: number | undefined;
+
     /**
      * List of registered {@link ReturnType}.
      *
@@ -223,29 +238,36 @@ export class Giuseppe {
      * them on the given [router]{@link Giuseppe#router}. After the router is configured, fires up the express
      * application with the given parameter.
      *
-     * @param {number} [port=8080] The port of the web application (express.listen argument).
+     * @param {number} [port] The port of the web application (express.listen argument). If no port is provided
+     *                        a random one is used.
      * @param {string} [baseUrl=''] Base url that is preceeding all urls in the system.
-     * @param {string} [hostname] Hostname that is passed to express.
-     * @param {Function} [callback] Callback that is used in express when the system is listening and ready.
      * @memberof Giuseppe
      */
-    public start(port: number = 8080, baseUrl: string = '', hostname?: string, callback?: Function): void {
+    public async start(port?: number, baseUrl: string = ''): Promise<void> {
+        const expressPort = port || await getRandomPort();
         const router = this.configureRouter(baseUrl);
         this.expressApp.use(router);
-        this._server = this.expressApp.listen.apply(this.expressApp, [port, hostname, callback].filter(Boolean));
+        this._server = await this.startup(expressPort);
+        this._port = expressPort;
     }
 
     /**
      * Closes the server of the application.
      *
-     * @param {Function} [callback] Callback that is passed to the server.
      * @memberof Giuseppe
      */
-    public stop(callback?: Function): void {
-        if (this._server) {
-            this._server.close(callback);
-            delete this._server;
-        }
+    public stop(): Promise<void> {
+        return new Promise(resolve => {
+            if (this._server) {
+                this._server.close(() => {
+                    delete this._server;
+                    delete this._port;
+                    resolve();
+                });
+                return;
+            }
+            resolve();
+        });
     }
 
     /**
@@ -452,4 +474,12 @@ export class Giuseppe {
 
         return true;
     }
+
+    private startup(port: number): Promise<Server> {
+        return new Promise(resolve => {
+            const server = this.expressApp.listen(port, () => {
+                resolve(server);
+            });
+        });
+    }
 }

src/utilities/RandomPort.ts

@@ -0,0 +1,20 @@
+import { createServer } from 'http';
+import { AddressInfo } from 'net';
+
+export function getRandomPort(): Promise<number> {
+    const server = createServer();
+    return new Promise((resolve, reject) => {
+        server.listen(0);
+        server.on('listening', () => {
+            try {
+                const port = (server.address() as AddressInfo).port;
+                server.close(() => {
+                    resolve(port);
+                });
+            } catch (e) {
+                reject(e);
+            }
+        });
+        server.on('error', reject);
+    });
+}

test/utilities/RandomPort.spec.ts

@@ -0,0 +1,30 @@
+import { getRandomPort } from '../../src/utilities/RandomPort';
+
+describe('RandomPort', () => {
+
+    describe('getRandomPort()', () => {
+
+        it('should return a random port', async () => {
+            const port = await getRandomPort();
+
+            expect(port).toBeGreaterThan(0);
+            expect(port).toBeLessThan(65536);
+        });
+
+        it('should return multiple random ports', async () => {
+            const ports = await Promise.all([
+                getRandomPort(),
+                getRandomPort(),
+                getRandomPort(),
+                getRandomPort(),
+            ]);
+
+            for (const port of ports) {
+                expect(port).toBeGreaterThan(0);
+                expect(port).toBeLessThan(65536);
+            }
+        });
+
+    });
+
+});