ultimate-express 1.0.0

package/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Run tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ] 
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Source Tree
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install --include=dev
+        
+      - name: Run tests
+        run: npm run test

package/EXPRESS_LICENSE

@@ -0,0 +1,26 @@
+Express.js License (only Express.js code)
+
+(The MIT License)
+
+Copyright (c) 2009-2014 TJ Holowaychuk <tj@vision-media.ca>
+Copyright (c) 2013-2014 Roman Shtylman <shtylman+expressjs@gmail.com>
+Copyright (c) 2014-2015 Douglas Christopher Wilson <doug@somethingdoug.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# µExpress
+
+The *Ultimate* Express. Fastest http server with **full** Express compatibility, based on µWebSockets.
+
+This library is a very fast re-implementation of Express.js 4.
+It is designed to be a drop-in replacement for Express.js, with the same API and functionality, while being much faster. It is not a fork of Express.js.  
+To make sure µExpress matches behavior of Express in all cases, we run all tests with Express first, and then with µExpress and compare results to make sure they match.  
+
+`npm install ultimate-express`
+
+![Node.js >= 16.0.0](https://img.shields.io/badge/Node.js-%3E=16.0.0-green)
+
+## Difference from similar projects
+
+Similar projects based on uWebSockets:
+
+- `express` on Bun - since Bun uses uWS for its HTTP module, Express is about 2.5 times faster than on Node.js with 25k req/sec instead of 10k req/sec normally, but still slower than µExpress at 60k req/sec because it doesn't do uWS-specific optimizations.
+- `hyper-express` - while having a similar API to Express, it's very far from being a drop-in replacement, and implements most of the functionality differently. This creates a lot of random quirks and issues, making the switch quite difficult. Built in middlewares are also very different.
+- `uwebsockets-express` - this library is closer to being a drop-in replacement, but misses a lot of APIs, depends on Express by calling it's methods under the hood and doesn't try to optimize routing by using native uWS router.
+
+## Differences from Express
+
+In a lot of cases, you can just replace `require("express")` with `require("ultimate-express")` and everything works the same. But there are some differences:
+
+- `case sensitive routing` is enabled by default.
+- Depending on how you send response, `Content-Length` header may be overwritten or not sent at all:
+- - on simple responses with res.send(), res.json(), etc. it's set automatically (any value you set with res.set() is overwritten)
+- - on streaming responses (piping, res.sendFile()) it's not sent because uWS uses chunked transfer encoding instead
+- - on responses without body, it *is* sent (useful for HEAD requests)
+- request body is only read for POST, PUT and PATCH requests by default. You can add additional methods by setting `body methods` to array with uppercased methods.
+- For HTTPS, instead of doing this:
+
+```js
+const https = require("https");
+const express = require("express");
+
+const app = express();
+
+https.createServer({
+    key: fs.readFileSync('path/to/key.pem'),
+    cert: fs.readFileSync('path/to/cert.pem')
+}, app).listen(3000, () => {
+    console.log('Server is running on port 3000');
+});
+```
+
+You have to pass `uwsOptions` to the `express()` constructor:
+```js
+const express = require("u-express");
+
+const app = express({
+    uwsOptions: {
+        // https://unetworking.github.io/uWebSockets.js/generated/interfaces/AppOptions.html
+        key_file_name: 'path/to/key.pem',
+        cert_file_name: 'path/to/cert.pem'
+    }
+});
+
+app.listen(3000, () => {
+    console.log('Server is running on port 3000');
+});
+```
+
+- This also applies to non-SSL HTTP too. Do not create http server manually, use `app.listen()` instead.
+
+## Performance tips
+
+1. µExpress tries to optimize routing as much as possible, but it's only possible if:
+- `case sensitive routing` is enabled (it is by default, unlike in normal Express).
+- only string paths without regex characters like *, +, (), {}, :param, etc. can be optimized.
+- only 1-level deep routers can be optimized.  
+  
+Optimized routes can be up to 10 times faster than normal routes, as they're using native uWS router and have pre-calculated path.
+
+2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for uExpress.
+
+3. Do not set `body methods` to read body of requests with GET method or other methods that don't need a body. Reading body makes server about 10k req/sec slower.
+
+4. By default, µExpress creates 1 worker thread for reading files (or 0 if your CPU has only 1 core). You can change this number by setting `fsThreads` to a different number in `express()`, or set to 0 to disable thread pool for file reading (`express({ fsThreads: 0 })`). Threads are shared between all express() instances, with largest fsThreads number being used. Using more threads will not necessarily improve performance. Sometimes not using threads at all is faster, please [test](https://github.com/wg/wrk/) both options.
+
+## Compatibility
+
+✅ - Full support (all features and options are supported)  
+🚧 - Partial support (some options are not supported)  
+❌ - Not supported  
+
+### express
+
+- ✅ express()
+- ✅ express.Router()
+- ✅ express.json()
+- ✅ express.urlencoded()
+- ✅ express.static()
+- ✅ express.text()
+- ✅ express.raw()
+- 🚧 express.request (this is not a constructor but a prototype for replacing methods)
+- 🚧 express.response (this is not a constructor but a prototype for replacing methods)
+
+### Application
+
+- ✅ app.listen()
+- ✅ app.METHOD() (app.get, app.post, etc.)
+- ✅ app.route()
+- ✅ app.all()
+- ✅ app.use()
+- ✅ app.mountpath
+- ✅ app.set()
+- ✅ app.get()
+- ✅ app.enable()
+- ✅ app.disable()
+- ✅ app.enabled()
+- ✅ app.disabled()
+- ✅ app.path()
+- ✅ app.param(name, callback)
+- ✅ app.param(callback)
+- ✅ app.engine()
+- ✅ app.render()
+- ✅ app.locals
+- ✅ app.settings
+- ✅ app.engines
+- ✅ app.on("mount")
+- ✅ HEAD method
+
+### Application settings
+
+- ✅ case sensitive routing
+- ✅ env
+- ✅ etag
+- ✅ jsonp callback name
+- ✅ json escape
+- ✅ json replacer
+- ✅ json spaces
+- ✅ query parser
+- ✅ strict routing
+- ✅ subdomain offset
+- ✅ trust proxy
+- ✅ views
+- ✅ view cache
+- ✅ view engine
+- ✅ x-powered-by
+
+### Request
+- ✅ implements Readable stream
+- ✅ req.app
+- ✅ req.baseUrl
+- ✅ req.body
+- ✅ req.cookies
+- ✅ req.fresh
+- ✅ req.hostname
+- ✅ req.headers
+- ✅ req.headersDistinct
+- ✅ req.rawHeaders
+- ✅ req.ip
+- ✅ req.ips
+- ✅ req.method
+- ✅ req.url
+- ✅ req.originalUrl
+- ✅ req.params
+- ✅ req.path
+- ✅ req.protocol
+- ✅ req.query
+- ✅ req.res
+- ✅ req.secure
+- ✅ req.signedCookies
+- ✅ req.stale
+- ✅ req.subdomains
+- ✅ req.xhr
+- 🚧 req.route (route implementation is different from Express)
+- 🚧 req.connection, req.socket (only `encrypted`, `remoteAddress`, `localPort` and `remotePort` are supported)
+- ✅ req.accepts()
+- ✅ req.acceptsCharsets()
+- ✅ req.acceptsEncodings()
+- ✅ req.acceptsLanguages()
+- ✅ req.get()
+- ✅ req.is()
+- ✅ req.param()
+- ✅ req.range()
+
+### Response
+
+- ✅ implements Writable stream
+- ✅ res.app
+- ✅ res.headersSent
+- ✅ res.req
+- ✅ res.locals
+- ✅ res.append()
+- ✅ res.attachment()
+- ✅ res.cookie()
+- ✅ res.clearCookie()
+- ✅ res.download()
+- ✅ res.end()
+- ✅ res.format()
+- ✅ res.getHeader(), res.get()
+- ✅ res.json()
+- ✅ res.jsonp()
+- ✅ res.links()
+- ✅ res.location()
+- ✅ res.redirect()
+- ✅ res.render()
+- ✅ res.send()
+- ✅ res.sendFile()
+- - ✅ options.maxAge
+- - ✅ options.root
+- - ✅ options.lastModified
+- - ✅ options.headers
+- - ✅ options.dotfiles
+- - ✅ options.acceptRanges
+- - ✅ options.cacheControl
+- - ✅ options.immutable
+- - ✅ Range header
+- - ✅ Setting ETag header
+- - ✅ If-Match header
+- - ✅ If-Modified-Since header
+- - ✅ If-Unmodified-Since header
+- - ✅ If-Range header
+- ✅ res.sendStatus()
+- ✅ res.header(), res.setHeader(), res.set()
+- ✅ res.status()
+- ✅ res.type()
+- ✅ res.vary()
+- ✅ res.removeHeader()
+- ✅ res.write()
+- ✅ res.writeHead()
+
+### Router
+
+- ✅ router.all()
+- ✅ router.METHOD() (router.get, router.post, etc.)
+- ✅ router.route()
+- ✅ router.use()
+- ✅ router.param(name, callback)
+- ✅ router.param(callback)
+- ✅ options.caseSensitive
+- ✅ options.strict
+- ✅ options.mergeParams
+
+## Tested middlewares
+
+Most of the middlewares that are compatible with Express are compatible with µExpress. Here's list of middlewares that we test for compatibility:
+
+- ✅ [body-parser](https://npmjs.com/package/body-parser)
+- ✅ [cookie-parser](https://npmjs.com/package/cookie-parser)
+- ✅ [cookie-session](https://npmjs.com/package/cookie-session)
+- ✅ [serve-static](https://npmjs.com/package/serve-static) (use `express.static()` instead for better performance)
+- ✅ [serve-index](https://npmjs.com/package/serve-index)
+- ✅ [cors](https://npmjs.com/package/cors)
+- ✅ [errorhandler](https://npmjs.com/package/errorhandler)
+- ✅ [method-override](https://npmjs.com/package/method-override)
+- ✅ [multer](https://npmjs.com/package/multer)
+- ✅ [response-time](https://npmjs.com/package/response-time)
+- ✅ [express-fileupload](https://npmjs.com/package/express-fileupload)
+- ✅ [express-session](https://npmjs.com/package/express-session)
+- ✅ [express-rate-limit](https://npmjs.com/package/express-rate-limit)
+- ✅ [vhost](https://npmjs.com/package/vhost)
+
+Middlewares that are confirmed to not work:
+
+- ❌ [compression](https://npmjs.com/package/compression) (doesn't error, but doesn't compress)
+
+## Tested view engines
+
+Any Express view engine should work. Here's list of engines we include in our test suite:
+
+- ✅ [ejs](https://npmjs.com/package/ejs)
+- ✅ [pug](https://npmjs.com/package/pug)
+- ✅ [express-dot-engine](https://npmjs.com/package/express-dot-engine)
+- ✅ [express-art-template](https://npmjs.com/package/express-art-template)
+- ✅ [express-handlebars](https://npmjs.com/package/express-handlebars)
+- ✅ [swig](https://npmjs.com/package/swig)

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "ultimate-express",
+  "version": "1.0.0",
+  "description": "The Ultimate Express. Fastest http server with full Express compatibility, based on uWebSockets.",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node tests/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dimdenGD/u-express.git"
+  },
+  "keywords": [
+    "express",
+    "http",
+    "fast",
+    "server",
+    "http server",
+    "https",
+    "https server",
+    "ws",
+    "websocket",
+    "websockets",
+    "uwebsockets",
+    "uws"
+  ],
+  "author": "dimden.dev",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/dimdenGD/u-express/issues"
+  },
+  "homepage": "https://github.com/dimdenGD/u-express#readme",
+  "dependencies": {
+    "accepts": "^1.3.8",
+    "body-parser": "^1.20.3",
+    "cookie": "^0.6.0",
+    "cookie-session": "^2.1.0",
+    "cookie-signature": "^1.2.1",
+    "etag": "^1.8.1",
+    "express-rate-limit": "^7.4.0",
+    "fresh": "^0.5.2",
+    "mime-types": "^2.1.35",
+    "ms": "^2.1.3",
+    "proxy-addr": "^2.0.7",
+    "qs": "^6.13.0",
+    "range-parser": "^1.2.1",
+    "statuses": "^2.0.1",
+    "tseep": "^1.2.2",
+    "type-is": "^1.6.18",
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.48.0",
+    "vary": "^1.1.2"
+  },
+  "devDependencies": {
+    "cookie-parser": "^1.4.6",
+    "cors": "^2.8.5",
+    "ejs": "^3.1.10",
+    "errorhandler": "^1.5.1",
+    "exit-hook": "^2.2.1",
+    "express": "^4.19.2",
+    "express-art-template": "^1.0.1",
+    "express-dot-engine": "^1.0.8",
+    "express-fileupload": "^1.5.1",
+    "express-handlebars": "^8.0.1",
+    "express-session": "^1.18.0",
+    "method-override": "^3.0.0",
+    "multer": "^1.4.5-lts.1",
+    "mustache-express": "^1.3.2",
+    "pako": "^2.1.0",
+    "pug": "^3.0.3",
+    "response-time": "^2.3.2",
+    "serve-index": "^1.9.1",
+    "serve-static": "^1.16.2",
+    "swig": "^1.4.2",
+    "vhost": "^3.0.2"
+  }
+}

package/src/application.js

@@ -0,0 +1,295 @@
+const uWS = require("uWebSockets.js");
+const Router = require("./router.js");
+const { removeDuplicateSlashes, defaultSettings, compileTrust, createETagGenerator } = require("./utils.js");
+const querystring = require("querystring");
+const qs = require("qs");
+const ViewClass = require("./view.js");
+const path = require("path");
+const os = require("os");
+const { Worker } = require("worker_threads");
+
+const cpuCount = os.cpus().length;
+
+let fsWorkers = [];
+let fsKey = 0;
+const fsCache = {};
+
+function createFsWorker() {
+    const fsWorker = new Worker(path.join(__dirname, 'workers/fs.js'));
+    fsWorkers.push(fsWorker);
+
+    fsWorker.on('message', (message) => {
+        if(message.err) {
+            fsCache[message.key].reject(new Error(message.err));
+        } else {
+            fsCache[message.key].resolve(message.data);
+        }
+        delete fsCache[message.key];
+    });
+    fsWorker.unref();
+
+    return fsWorker;
+}
+
+class Application extends Router {
+    constructor(settings = {}) {
+        super(settings);
+        if(!settings?.uwsOptions) {
+            settings.uwsOptions = {};
+        }
+        if(typeof settings.fsThreads !== 'number') {
+            settings.fsThreads = cpuCount > 1 ? 1 : 0;
+        }
+        if(settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name) {
+            this.uwsApp = uWS.SSLApp(settings.uwsOptions);
+            this.ssl = true;
+        } else {
+            this.uwsApp = uWS.App(settings.uwsOptions);
+            this.ssl = false;
+        }
+        this.cache = {};
+        this.engines = {};
+        this.locals = {
+            settings: this.settings
+        };
+        this.listenCalled = false;
+        this.fsWorkers = [];
+        for(let i = 0; i < settings.fsThreads; i++) {
+            if(fsWorkers[i]) {
+                this.fsWorkers[i] = fsWorkers[i];
+            } else {
+                this.fsWorkers[i] = createFsWorker();
+            }
+        }
+        this.port = undefined;
+        for(const key in defaultSettings) {
+            if(typeof this.settings[key] === 'undefined') {
+                if(typeof defaultSettings[key] === 'function') {
+                    this.settings[key] = defaultSettings[key]();
+                } else {
+                    this.settings[key] = defaultSettings[key];
+                }
+            }
+        }
+        this.set('view', ViewClass);
+        this.set('views', path.resolve('views'));
+    }
+
+    readFileWithWorker(path) {
+        return new Promise((resolve, reject) => {
+            const fsWorker = this.fsWorkers[Math.floor(Math.random() * this.fsWorkers.length)];
+            const key = fsKey++;
+            fsWorker.postMessage({ key, type: 'readFile', path });
+            fsCache[key] = { resolve, reject };
+            if(key > 1000000) {
+                fsKey = 0;
+            }
+        });
+    }
+
+
+    set(key, value) {
+        if(key === 'trust proxy') {
+            if(!value) {
+                delete this.settings['trust proxy fn'];
+            } else {
+                this.settings['trust proxy fn'] = compileTrust(value);
+            }
+        } else if(key === 'query parser') {
+            if(value === 'extended') {
+                this.settings['query parser fn'] = qs.parse;
+            } else if(value === 'simple') {
+                this.settings['query parser fn'] = querystring.parse;
+            } else if(typeof value === 'function') {
+                this.settings['query parser fn'] = value;
+            } 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);
+            return this;
+        } else if(key === 'etag') {
+            if(typeof value === 'function') {
+                this.settings['etag fn'] = value;
+            } else {
+                switch(value) {
+                    case true:
+                    case 'weak':
+                        this.settings['etag fn'] = createETagGenerator({ weak: true });
+                        break;
+                    case 'strong':
+                        this.settings['etag fn'] = createETagGenerator({ weak: false });
+                        break;
+                    case false:
+                        delete this.settings['etag fn'];
+                        break;
+                    default:
+                        throw new Error(`Invalid etag mode: ${value}`);
+                }
+            }
+        }
+
+        this.settings[key] = value;
+        return this;
+    }
+
+    enable(key) {
+        this.settings[key] = true;
+        return this;
+    }
+
+    disable(key) {
+        this.settings[key] = false;
+        return this;
+    }
+
+    enabled(key) {
+        return !!this.settings[key];
+    }
+
+    disabled(key) {
+        return !this.settings[key];
+    }
+
+    #createRequestHandler() {
+        this.uwsApp.any('/*', async (res, req) => {
+
+            const request = new this._request(req, res, this);
+            const response = new this._response(res, request, this);
+            request.res = response;
+            response.req = request;
+            res.onAborted(() => {
+                const err = new Error('Request aborted');
+                err.code = 'ECONNABORTED';
+                response.aborted = true;
+                response.socket.emit('error', err);
+            });
+
+            let matchedRoute = await this._routeRequest(request, response);
+
+            if(!matchedRoute && !res.aborted && !response.headersSent) {
+                response.status(404);
+                response.send(this._generateErrorPage(`Cannot ${request.method} ${request.path}`));
+            }
+        });
+    }
+
+    listen(port, callback) {
+        this.#createRequestHandler();
+        if(!callback && typeof port === 'function') {
+            callback = port;
+            port = 0;
+        }
+        let fn = 'listen';
+        if(typeof port !== 'number') {
+            if(!isNaN(Number(port))) {
+                port = Number(port);
+            } else {
+                fn = 'listen_unix';
+            }
+        }
+        this.listenCalled = true;
+        this.uwsApp[fn](port, socket => {
+            if(!socket) {
+                let err = new Error('Failed to listen on port ' + port + '. No permission or address already in use.');
+                throw err;
+            }
+            this.port = uWS.us_socket_local_port(socket);
+            callback(this.port);
+        });
+    }
+
+    address() {
+        return { port: this.port };
+    }
+
+    path() {
+        let paths = [this.mountpath];
+        let parent = this.parent;
+        while(parent) {
+            paths.unshift(parent.mountpath);
+            parent = parent.parent;
+        }
+        let path = removeDuplicateSlashes(paths.join(''));
+        return path === '/' ? '' : path;
+    }
+
+    engine(ext, fn) {
+        if (typeof fn !== 'function') {
+            throw new Error('callback function required');
+        }
+        const extension = ext[0] !== '.'
+            ? '.' + ext
+            : ext;
+        this.engines[extension] = fn;
+        return this;
+    }
+
+    render(name, options, callback) {
+        if(typeof options === 'function') {
+            callback = options;
+            options = {};
+        }
+        if(!options) {
+            options = {};
+        } else {
+            options = Object.assign({}, options);
+        }
+        for(let key in this.locals) {
+            options[key] = this.locals[key];
+        }
+
+        if(options._locals) {
+            for(let key in options._locals) {
+                options[key] = options._locals[key];
+            }
+        }
+
+        if(options.cache == null) {
+            options.cache = this.enabled('view cache');
+        }
+
+        let view;
+        if(options.cache) {
+            view = this.cache[name];
+        }
+
+        if(!view) {
+            const View = this.get('view');
+            view = new View(name, {
+                defaultEngine: this.get('view engine'),
+                root: this.get('views'),
+                engines: this.engines
+            });
+            if(!view.path) {
+                const dirs = Array.isArray(view.root) && view.root.length > 1
+                    ? 'directories "' + view.root.slice(0, -1).join('", "') + '" or "' + view.root[view.root.length - 1] + '"'
+                    : 'directory "' + view.root + '"';
+
+                const err = new Error(`Failed to lookup view "${name}" in views ${dirs}`);
+                err.view = view;
+                return callback(err);
+            }
+
+            if(options.cache) {
+                this.cache[name] = view;
+            }
+        }
+
+        try {
+            view.render(options, callback);
+        } catch(err) {
+            callback(err);
+        }
+    }
+}
+
+module.exports = function(options) {
+    return new Application(options);
+}