fulmine.js 5.0.0-rc.1 → 5.0.0

package/README.md

@@ -36,7 +36,7 @@ Compatibility here is not a claim, it is a test suite. Every test runs against r
 
 Fulmine is faster than Express where the framework itself is doing the work, and the same speed where it is not. Both halves of that sentence matter, so here is the honest version.
 
-**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. These land between 1.7x and 3x: plain routing 1.7x to 2.3x, an API endpoint with params and a query 1.8x to 2.7x, nested routers 2.2x to 2.5x, a urlencoded body 2.7x to 3x.
+**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. Plain routing lands between 1.9x and 3.2x: hello-world 1.9x to 2.2x, an API endpoint with params and a query 2.6x to 3.2x, nested routers 2x to 2.5x, a urlencoded body 2.6x to 3.2x, 5000 concurrent connections 2.4x to 2.7x. Route tables are where the native router shows: a thousand routes 5.4x to 8.1x, with a parameter in every one of them 5.8x to 8.7x, a parameterised route in a mounted router 3.8x to 5.9x. Those routes go to µWS's own router instead of being scanned, so the gap grows with the table instead of shrinking. The one routing scenario still even is a chain of 100 middlewares, 0.95x to 1x, where the cost is calling application code a hundred times rather than routing.
 
 **Where it is a wash.** Any request whose cost is dominated by work both servers hand to the same library. A 512 KiB JSON body is `JSON.parse`, a gzipped response is zlib, a hashed upload is OpenSSL, a 5 MiB stream is memory bandwidth. On those the ratio is capped by arithmetic somewhere around 1.0x to 1.2x, and no amount of work on either server moves it. The benchmark labels those rows rather than quietly publishing them as if the two were equivalent.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.0.0-rc.1",
+    "version": "5.0.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -73,6 +73,7 @@
         "fast-querystring": "^1.1.2",
         "fast-zlib": "^2.0.1",
         "fresh": "^2.0.0",
+        "iconv-lite": "^0.7.3",
         "mime-types": "^3.0.2",
         "ms": "^2.1.3",
         "proxy-addr": "^2.0.7",

package/src/application.js

@@ -117,6 +117,11 @@ class Application extends Router {
         this.listening = false;
         // the host handed to listen(), which is all address() has to go on
         this._listenHost = undefined;
+        // the uWS listen socket, and the responses being served right now: close() stops the
+        // first and waits for the second, the way node's server.close() does
+        this._listenSocket = undefined;
+        this._pendingResponses = new Set();
+        this._draining = false;
         for (const key in defaultSettings) {
             if (typeof this.settings[key] === "undefined") {
                 if (typeof defaultSettings[key] === "function") {
@@ -169,7 +174,7 @@ class Application extends Router {
      * Reads or writes an application setting. One argument is the getter, and the check is on
      * `arguments.length`, so `set(key, undefined)` still writes. Some keys have a side effect:
      * `trust proxy`, `query parser` and `etag` compile the value into a function kept beside it,
-     * `views` becomes an absolute path, and `env` set to "production" turns the view cache on.
+     * and `views` becomes an absolute path.
      *
      * @param {string} key setting name
      * @param {*} [value] value to store; omit to read instead
@@ -195,14 +200,9 @@ class Application extends Router {
             } else {
                 this.settings["query parser fn"] = undefined;
             }
-        } else if (key === "env") {
-            if (value === "production") {
-                this.settings["view cache"] = true;
-            } else {
-                this.settings["view cache"] = undefined;
-            }
         } else if (key === "views") {
-            this.settings[key] = path.resolve(value);
+            // a list of directories is searched in order by View.lookup, each resolved here once
+            this.settings[key] = Array.isArray(value) ? value.map((dir) => path.resolve(dir)) : path.resolve(value);
             return this;
         } else if (key === "etag") {
             if (typeof value === "function") {
@@ -268,6 +268,27 @@ class Application extends Router {
         return !this.settings[key];
     }
 
+    /**
+     * Router's handleRequest plus the bookkeeping a graceful close() needs: every live response
+     * is held in a set until it finishes, so close() knows when the last one is done. Native
+     * routes and the catch-all both come through here, since both call it on the app.
+     *
+     * @param {any} res uWS response
+     * @param {any} req uWS request, readable only during this call
+     * @returns {{request: any, response: any}}
+     */
+    handleRequest(res, req) {
+        const handled = super.handleRequest(res, req);
+        const response = handled.response;
+        this._pendingResponses.add(response);
+        // removal rides the close listener the Response constructor already has, since a second
+        // once() per request measured a tenth of a microsecond on the hot path.
+        // An aborted response only flips its flags without emitting 'close', which is why
+        // close()'s drain also sweeps the set by those flags instead of trusting this alone
+        response._pendingIn = this._pendingResponses;
+        return handled;
+    }
+
     /**
      * Registers the catch-all uWS handler, which is what serves every request that no optimized
      * route took natively. It walks this app's own chain and, when nothing in it answered, decides
@@ -277,9 +298,19 @@ class Application extends Router {
         this.uwsApp.any("/*", async (res, req) => {
             const { request, response } = this.handleRequest(res, req);
 
-            const matchedRoute = await this._routeRequest(request, response);
-            if (!matchedRoute && !response.headersSent && !response.aborted) {
-                this._endUnmatched(request, response);
+            try {
+                const matchedRoute = await this._routeRequest(request, response);
+                if (!matchedRoute && !response.headersSent && !response.aborted) {
+                    this._endUnmatched(request, response);
+                }
+            } catch (err) {
+                // an internal throw answers 500 as express's final handler would, instead of
+                // dying as an unhandled rejection
+                if (response.aborted || response.finished) {
+                    console.error(err);
+                } else {
+                    this._handleError(err, null, request, response);
+                }
             }
         });
     }
@@ -311,6 +342,11 @@ class Application extends Router {
             callback = host;
             host = undefined;
         }
+        // bare listen() and listen(undefined, cb) bind an OS-assigned port, as node does; left
+        // undefined the port fell through to the unix-socket branch below
+        if (port == null) {
+            port = 0;
+        }
         // uWS runs this handler from inside its own listen(), so everything it hands back to the
         // caller is deferred a tick. Express binds synchronously too but reports through events,
         // and node emits both 'listening' and 'error' from a process.nextTick.
@@ -337,6 +373,8 @@ class Application extends Router {
             this.port = uWS.us_socket_local_port(socket);
             this.listening = true;
             this._listenHost = host;
+            // kept so close() can stop accepting without dropping what is in flight
+            this._listenSocket = socket;
             process.nextTick(() => {
                 // `this` is the app, which is what listen() returns here. Express binds it to the
                 // http.Server, which is what listen() returns there, so
@@ -451,20 +489,21 @@ class Application extends Router {
         // render exists to hand the result somewhere, so there is always a callback by this point:
         // either the third argument or the second one, shuffled above
         const done = /** @type {(err: Error|null, html?: string) => void} */ (callback);
-        if (!options) {
-            options = new NullObject();
-        } else {
-            options = Object.assign({}, options);
-        }
+        // express's order, least specific first: app.locals, then res.locals riding in as _locals,
+        // and what was passed to this call wins over both
+        const opts = options || new NullObject();
+        options = new NullObject();
         for (const key in this.locals) {
             options[key] = this.locals[key];
         }
-
-        if (options._locals) {
-            for (const key in options._locals) {
-                options[key] = options._locals[key];
+        if (opts._locals) {
+            for (const key in opts._locals) {
+                options[key] = opts._locals[key];
             }
         }
+        for (const key in opts) {
+            options[key] = opts[key];
+        }
 
         if (options.cache == null) {
             options.cache = this.enabled("view cache");
@@ -511,7 +550,13 @@ class Application extends Router {
     }
 
     /**
-     * Stops listening and emits 'close'.
+     * Stops accepting connections, lets in-flight requests finish, then emits 'close'.
+     *
+     * Node's server.close(), which Express hands back from listen(), only closes the listen
+     * socket and waits for what is being served; uWS's close() forcefully terminates every
+     * connection, so calling it first aborted whatever a graceful shutdown was waiting for.
+     * It still runs, but only once the last pending response is done, to drop the idle
+     * keep-alive connections nothing else would close.
      *
      * The callback is the first 'close' listener, so it runs before any added afterwards. Closing
      * a server that was not listening still calls back, with an ERR_SERVER_NOT_RUNNING error, the
@@ -522,9 +567,6 @@ class Application extends Router {
      */
     close(callback) {
         const wasListening = this.listening;
-        if (this.listenCalled && wasListening) {
-            this.uwsApp.close();
-        }
         this.listening = false;
         // in Express the close callback is nothing more than the first 'close' listener, and a
         // server that was not running still gets called back, with an error
@@ -539,7 +581,41 @@ class Application extends Router {
                 callback(err);
             });
         }
-        process.nextTick(() => this.emit("close"));
+        if (!this.listenCalled || !wasListening) {
+            // a close while a drain is underway does not emit again: the pending drain's single
+            // 'close' serves both calls, which is what node does too
+            if (!this._draining) {
+                process.nextTick(() => this.emit("close"));
+            }
+            return this;
+        }
+        if (this._listenSocket) {
+            uWS.us_listen_socket_close(this._listenSocket);
+            this._listenSocket = undefined;
+        }
+        this._draining = true;
+        const finish = () => {
+            this._draining = false;
+            this.uwsApp.close();
+            this.emit("close");
+        };
+        if (this._pendingResponses.size === 0) {
+            process.nextTick(finish);
+            return this;
+        }
+        // a finished response emits 'close' and removes itself; an aborted one only flips its
+        // flags, so the drain sweeps by them. The timer also keeps the loop alive until done.
+        const sweep = setInterval(() => {
+            for (const response of this._pendingResponses) {
+                if (response.finished || response.aborted) {
+                    this._pendingResponses.delete(response);
+                }
+            }
+            if (this._pendingResponses.size === 0) {
+                clearInterval(sweep);
+                finish();
+            }
+        }, 10);
         return this;
     }
 }

package/src/declarative.js

@@ -220,9 +220,8 @@ module.exports = function compileDeclarative(cb, app) {
         }
 
         const [req, res] = args;
-        let queryName,
-            paramsName,
-            queries = [],
+        let queryName, paramsName;
+        const queries = [],
             params = [];
 
         if (fn.params[0].type === "ObjectPattern") {
@@ -384,12 +383,14 @@ module.exports = function compileDeclarative(cb, app) {
                 if (call.arguments[0].type !== "Literal" || call.arguments[1].type !== "Literal") {
                     return false;
                 }
-                let [header, value] = [call.arguments[0].value, call.arguments[1].value];
+                // String() at capture: a numeric literal would reach uWS's writeHeader as itself,
+                // and uWS refuses anything that is not a string
+                let [header, value] = [call.arguments[0].value, String(call.arguments[1].value)];
                 const name = String(header).toLowerCase();
                 // res.set charsets a content-type and res.setHeader does not, since the second is
                 // node's and node does not know what a media type is
                 if (call.obj.propertyName !== "setHeader" && name === "content-type") {
-                    value = withDefaultCharset(String(value));
+                    value = withDefaultCharset(value);
                 }
                 const index = headers.findIndex((entry) => String(entry[0]).toLowerCase() === name);
                 if (index === -1) {
@@ -409,7 +410,7 @@ module.exports = function compileDeclarative(cb, app) {
                 if (call.arguments[0].type !== "Literal" || call.arguments[1].type !== "Literal") {
                     return false;
                 }
-                headers.push([call.arguments[0].value, call.arguments[1].value]);
+                headers.push([call.arguments[0].value, String(call.arguments[1].value)]);
             } else if (call.obj.propertyName === "sendStatus") {
                 if (call.arguments[0].type !== "Literal") {
                     return false;
@@ -552,6 +553,11 @@ module.exports = function compileDeclarative(cb, app) {
                          * @returns {boolean}
                          */
                         function check(node) {
+                            // only "+" concatenates; any other operator computes a value the
+                            // parts cannot represent, so the handler falls back
+                            if (node.operator !== "+") {
+                                return false;
+                            }
                             if (node.right.type === "Literal") {
                                 stuff.push({ type: "text", value: node.right.value });
                             } else if (node.right.type === "MemberExpression") {
@@ -602,12 +608,14 @@ module.exports = function compileDeclarative(cb, app) {
 
         let decRes = new uWSAny.DeclarativeResponse();
 
-        if (statusCode != 200) {
-            const statusMessage = statuses.message[statusCode] ?? "";
-            decRes = decRes.writeStatus(`${statusCode} ${statusMessage}`.trim());
-            if (!headers.some((header) => header[0].toLowerCase() === "content-type")) {
-                decRes = decRes.writeHeader("content-type", "text/plain; charset=utf-8");
-            }
+        if (statusCode !== 200) {
+            const statusMessage = statuses.message[statusCode] ?? "unknown";
+            decRes = decRes.writeStatus(`${statusCode} ${statusMessage}`);
+        }
+        // only sendStatus types its body: it goes through res.type("txt") on the ordinary path,
+        // while status(n).end() sends no Content-Type at all, in Express and here alike
+        if (sendStatusUsed && !headers.some((header) => header[0].toLowerCase() === "content-type")) {
+            decRes = decRes.writeHeader("content-type", "text/plain; charset=utf-8");
         }
 
         // the same two the ordinary path seeds every response with. Without them a route answered