[POC] feat!: drop cordova-serve

lib/Api.js

@@ -350,8 +350,16 @@ class Api {
             .then(() => require('./build').run(buildOptions));
     }
 
-    async run (runOptions) {
-        return require('./run').run(runOptions);
+    async run (runOptions = {}) {
+        // Gets the '<content src="" />' value from 'config.xml'.
+        // This will be appended to the URL printed on terminal.
+        runOptions.startUrl = this.config.doc.find('content')?.attrib?.src || 'index.html';
+        // Removes prefix slash if present. The printout already contains the "/".
+        if (runOptions.startUrl.startsWith('/')) {
+            runOptions.startUrl = runOptions.startUrl.slice(1);
+        }
+
+        return require('./run').run(this.locations, runOptions);
     }
 
     async clean (cleanOptions) {

lib/DevServer.js

@@ -0,0 +1,220 @@
+/*
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+*/
+
+const http = require('node:http');
+const https = require('node:https');
+const fs = require('node:fs');
+const { styleText } = require('node:util');
+const express = require('express');
+const compression = require('compression');
+const { default: open, apps: supportedBrowsers } = require('open');
+
+// TODO: Replace with String.dedent once it's supported by our minimum Node.js version.
+const dedent = require('string-dedent');
+
+/**
+ * @typedef DevServerOptions
+ * @type {object}
+ * @property {string} ssl-cert-file - path to the certificate file
+ * @property {string} ssl-key-file - path to the key file
+ * @property {number} port
+ * @property {string} startUrl - URI that is appended to <scheme>://localhost:<port>/ (default = index.html)
+ * @property {express.Router} router - .
+ * @property {string[]} argv - browser arguments
+ */
+
+/**
+ * @class DevServer
+ */
+class DevServer {
+    /** @type {express.Express} */
+    app;
+
+    /** @type {URL} URL to the app */
+    appUrl;
+
+    /** @type {http.Server|https.Server} */
+    #server;
+
+    /** @type {DevServerOptions} */
+    #serverOpts;
+
+    /** @type {object} */
+    #projectLocationPaths;
+
+    /** @type {string} scheme that the app will be served from */
+    #scheme;
+
+    /** @type {number} port that the app will be served from */
+    #port;
+
+    /** @type {boolean} flag to check if the host machine is darwin */
+    static #isDarwin = process.platform === 'darwin';
+
+    /**
+     *
+     * @param {DevServerOptions} serverOpts
+     */
+    constructor (serverOpts = {}, projectLocationPaths = {}) {
+        this.#serverOpts = serverOpts || {};
+        this.#projectLocationPaths = projectLocationPaths || {};
+
+        this.#createApp();
+    }
+
+    /**
+     * Creates and stores the Express instance on app.
+     */
+    #createApp () {
+        if (!this.#projectLocationPaths.www) {
+            throw new Error('Missing path to the project\'s platform www directory.');
+        }
+
+        this.app = express();
+
+        // Attach this before anything else to provide status output
+        this.app.use(this.#appStatusHandler);
+        this.app.use(compression());
+
+        if (this.#serverOpts.router) {
+            this.app.use(this.#serverOpts.router);
+        }
+
+        if (this.#projectLocationPaths.www) {
+            this.app.use(express.static(this.#projectLocationPaths.www));
+        }
+    }
+
+    /**
+     * @returns {Promise} resolves to this instance or rejects with an error.
+     */
+    async createAndLaunchServer () {
+        return new Promise((resolve, reject) => {
+            let httpsServOptions;
+            try {
+                httpsServOptions = {
+                    cert: fs.readFileSync(this.#serverOpts['ssl-cert-file']),
+                    key: fs.readFileSync(this.#serverOpts['ssl-key-file'])
+                };
+            } catch (e) {
+                // If any one of them fails to read then we dont have what we need for HTTPS
+                httpsServOptions = undefined;
+            }
+
+            this.#server = httpsServOptions
+                ? https.Server(httpsServOptions, this.app)
+                : http.Server(this.app);
+
+            this.#server.listen(this.#serverOpts.port || undefined);
+
+            this.#scheme = httpsServOptions ? 'https' : 'http';
+            this.#port = this.#server?.address()?.port;
+
+            this.#server.once('listening', () => {
+                this.#serverOnListening(resolve);
+            });
+            this.#server.once('error', (e) => {
+                reject(e);
+            });
+        });
+    }
+
+    // MARK: App Handlers
+
+    #appStatusHandler (req, res, next) {
+        res.on('finish', function () {
+            const statusColor = this.statusCode === 404 ? 'red' : 'green';
+            const statusCode = styleText(statusColor, this.statusCode.toString());
+
+            let msg = `${statusCode} ${this.req.originalUrl}`;
+
+            const encoding = this.getHeader('content-encoding');
+            if (encoding) {
+                msg += styleText('gray', ` (${encoding})`);
+            }
+            console.log(msg);
+        });
+        next();
+    }
+
+    // MARK: HTTP Listeners
+
+    /**
+     * Server's on listening handler
+     *
+     * @param {Promise.resolve} resolve
+     * @param {Promise.reject} reject
+     */
+    #serverOnListening (resolve, reject) {
+        // The app url to be opened when target is not none.
+        this.appUrl = new URL(`${this.#scheme}://localhost:${this.#port}/${this.#serverOpts.startUrl}`);
+
+        const developmentWarning = dedent`
+            This development server is for testing only. Do not use it in production.
+            For advanced debugging, use your own setup and serve the app content located at:
+
+            ${this.#projectLocationPaths.www}
+        `;
+        const message = dedent`
+            Static file server running on: ${styleText(['green', 'bold'], this.appUrl.href)}
+
+            ${styleText(['yellow', 'bold'], developmentWarning)}
+
+            (${DevServer.#isDarwin ? 'Control' : 'CTRL'} + C to shut down)\n
+        `;
+        console.log(message);
+
+        // Check if the browser should open.
+        const browserTarget = this.#serverOpts?.target?.toString().toLowerCase() ?? 'default';
+        if (browserTarget !== 'none') {
+            this.#openBrowser(browserTarget);
+        }
+
+        resolve(this);
+    }
+
+    // MARK: Handlers support methods
+
+    #openBrowser (browserTarget) {
+        const openOptions = { app: {} };
+
+        const filteredSupportedBrowsers = Object.keys(supportedBrowsers)
+            .filter(b => !['browser', 'browserPrivate'].includes(b));
+
+        if (browserTarget !== 'default') {
+            if (!filteredSupportedBrowsers.includes(browserTarget)) {
+                console.log(styleText('red', dedent`
+                    Invalid target (${browserTarget}) was supplied and will fallback to default.
+                    Valid targets: ${filteredSupportedBrowsers.join(', ')}\n
+                `));
+            } else {
+                openOptions.app.name = supportedBrowsers[browserTarget];
+            }
+        }
+
+        const browserArgs = this.#serverOpts?.argv ?? [];
+        if ((browserArgs.length ?? 0) > 0) {
+            openOptions.app.arguments = browserArgs;
+        }
+
+        open(this.appUrl.href, openOptions);
+    }
+}
+
+module.exports = DevServer;

lib/run.js

@@ -17,51 +17,10 @@
     under the License.
 */
 
-const fs = require('node:fs');
-const path = require('node:path');
-const url = require('node:url');
+const DevServer = require('./DevServer');
 
-const cordovaServe = require('cordova-serve');
+module.exports.run = function (projectLocations, serverOpts = {}) {
+    const server = new DevServer(serverOpts, projectLocations);
 
-module.exports.run = function (args) {
-    // defaults
-    args.port = args.port || 8000;
-    args.target = args.target || 'default'; // make default the system browser
-    args.noLogOutput = args.silent || false;
-
-    const wwwPath = path.join(__dirname, '../../www');
-    const manifestFilePath = path.resolve(path.join(wwwPath, 'manifest.json'));
-
-    let startPage;
-
-    // get start page from manifest
-    if (fs.existsSync(manifestFilePath)) {
-        try {
-            const manifest = require(manifestFilePath);
-            startPage = manifest.start_url;
-        } catch (err) {
-            console.log(`failed to require manifest ... ${err}`);
-        }
-    }
-
-    const server = cordovaServe();
-    server.servePlatform('browser', { port: args.port, noServerInfo: true, noLogOutput: args.noLogOutput })
-        .then(function () {
-            if (!startPage) {
-                // failing all else, set the default
-                startPage = 'index.html';
-            }
-
-            const projectUrl = (new url.URL(`http://localhost:${server.port}/${startPage}`)).href;
-
-            console.log(`startPage = ${startPage}`);
-            console.log(`Static file server running @ ${projectUrl}\nCTRL + C to shut down`);
-            return server.launchBrowser({ target: args.target, url: projectUrl });
-        })
-        .catch(function (error) {
-            console.log(error.message || error.toString());
-            if (server.server) {
-                server.server.close();
-            }
-        });
+    return server.createAndLaunchServer();
 };