Building a High-Performance Web Framework on uWebSockets

When building modern web applications, performance, scalability, and developer experience are critical factors. With this in mind, I set out to create a lightweight web framework inspired by ExpressJS for simplicity and ElysiaJS for innovation, leveraging the high-performance capabilities of uWebSockets.

Framework Overview

This framework combines the approachable design of ExpressJS with modern features, such as strong typing and middleware support. Below are its core features:

Key Features

1. HTTP Methods: Supports standard HTTP methods (get(), post(), delete(), patch()) and an any() method to handle all HTTP methods for a given endpoint.

2. Middleware: Add middleware using the use() method, optionally scoping it to specific paths.

3. Router: Includes a router similar to ExpressJS, which can be attached to the app using the attach() method. Routers also support all the HTTP methods above.

4. Strongly Typed Endpoints: Using Zod for validation and type inference, endpoint handlers receive strongly-typed params, query, requestBody, cookie, and signedCookies. Validation is performed automatically, throwing a ZodError for invalid inputs.

5. Global Error Handling: The app.error() method allows defining global error-handling middleware.

6. Educational Value: This framework showcases how features can be implemented in a high-performance, lightweight web server.

Benchmarks

To assess the framework’s performance, I conducted benchmarks comparing it to ExpressJS. Here’s how they stack up:

Test Environment

• Machine: MacBook Air 2022, M2 Processor, 8GB RAM
• Test Command:

npx autocannon -d 30 -c 1000 [endpoint]

Framework Benchmark

App Setup

import { App } from "http-framework";

const app = new App();

app.get("/", {}, (req, res) => {
  res.end();
});

app.listen(3000);

Results

Requests/Second: ~117,348
Latency: ~0.03ms
Bytes/Second: ~10.8MB
Total Requests: ~3.5M in 30 seconds

Detailed Results

┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬───────┐
│ Stat │ 2.5% │ 50% │ 97.5% │ 99% │ Avg │ Stdev │ Max │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼───────┤
│ Latency │ 0 ms │ 0 ms │ 0 ms │ 1 ms │ 0.03 ms │ 0.16 ms │ 13 ms │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴───────┘
┌───────────┬─────────┬─────────┬─────────┬─────────┬────────────┬──────────┬─────────┐
│ Stat │ 1% │ 2.5% │ 50% │ 97.5% │ Avg │ Stdev │ Min │
├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼──────────┼─────────┤
│ Req/Sec │ 111,039 │ 111,039 │ 117,695 │ 118,143 │ 117,348.27 │ 1,259.57 │ 111,021 │
├───────────┼─────────┼─────────┼─────────┼─────────┼────────────┼──────────┼─────────┤
│ Bytes/Sec │ 10.2 MB │ 10.2 MB │ 10.8 MB │ 10.9 MB │ 10.8 MB │ 116 kB │ 10.2 MB │
└───────────┴─────────┴─────────┴─────────┴─────────┴────────────┴──────────┴─────────┘

3521k requests in 30.01s, 324 MB read

ExpressJS Benchmark

App Setup

const express = require("express");

const app = express();

app.get("/", (req, res) => {
  res.end();
});

app.listen(3001);

Results

Requests/Second: ~25,642
Latency: ~3.24ms
Bytes/Second: ~3.72MB
Total Requests: ~769K in 30 seconds

Detailed Results

┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬────────┐
│ Stat │ 2.5% │ 50% │ 97.5% │ 99% │ Avg │ Stdev │ Max │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼────────┤
│ Latency │ 3 ms │ 3 ms │ 5 ms │ 5 ms │ 3.24 ms │ 0.98 ms │ 198 ms │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴────────┘
┌───────────┬─────────┬─────────┬─────────┬─────────┬───────────┬─────────┬─────────┐
│ Stat │ 1% │ 2.5% │ 50% │ 97.5% │ Avg │ Stdev │ Min │
├───────────┼─────────┼─────────┼─────────┼─────────┼───────────┼─────────┼─────────┤
│ Req/Sec │ 23,231 │ 23,231 │ 25,727 │ 25,823 │ 25,642.67 │ 451.25 │ 23,230 │
├───────────┼─────────┼─────────┼─────────┼─────────┼───────────┼─────────┼─────────┤
│ Bytes/Sec │ 3.37 MB │ 3.37 MB │ 3.73 MB │ 3.75 MB │ 3.72 MB │ 65.4 kB │ 3.37 MB │
└───────────┴─────────┴─────────┴─────────┴─────────┴───────────┴─────────┴─────────┘

769k requests in 30.02s, 112 MB read

The framework achieved ~4.5x higher throughput and significantly lower latency compared to ExpressJS.

Middleware Benchmarks

I added a single middleware function to both the framework and ExpressJS to log the HTTP method of incoming requests.

Framework App Changes

app.get(
  "/",
  {},
  (req, res, next) => {
    console.log(req.method);
    next();
  },
  (req, res) => {
    res.end();
  },
);

Framework Results

Requests/Second: ~88,785
Latency: ~0.93ms
Bytes/Second: ~8.17MB
Total Requests: ~2.66M in 30 seconds

Detailed Results

┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬───────┐
│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%  │ Avg     │ Stdev   │ Max   │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼───────┤
│ Latency │ 0 ms │ 1 ms │ 1 ms  │ 2 ms │ 0.93 ms │ 0.36 ms │ 13 ms │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴───────┘
┌───────────┬────────┬────────┬────────┬─────────┬───────────┬──────────┬────────┐
│ Stat      │ 1%     │ 2.5%   │ 50%    │ 97.5%   │ Avg       │ Stdev    │ Min    │
├───────────┼────────┼────────┼────────┼─────────┼───────────┼──────────┼────────┤
│ Req/Sec   │ 83,711 │ 83,711 │ 89,151 │ 89,791  │ 88,785.07 │ 1,073.18 │ 83,651 │
├───────────┼────────┼────────┼────────┼─────────┼───────────┼──────────┼────────┤
│ Bytes/Sec │ 7.7 MB │ 7.7 MB │ 8.2 MB │ 8.26 MB │ 8.17 MB   │ 98.9 kB  │ 7.7 MB │
└───────────┴────────┴────────┴────────┴─────────┴───────────┴──────────┴────────┘

ExpressJS App Changes

app.get(
  "/",
  (req, res, next) => {
    console.log(req.method);
    next();
  },
  (req, res) => {
    res.end();
  },
);

ExpressJS Results

Requests/Second: ~21,748
Latency: ~4.2ms
Bytes/Second: ~3.15MB
Total Requests: ~653K in 30 seconds

Detailed Results

┌─────────┬──────┬──────┬───────┬──────┬────────┬─────────┬────────┐
│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%  │ Avg    │ Stdev   │ Max    │
├─────────┼──────┼──────┼───────┼──────┼────────┼─────────┼────────┤
│ Latency │ 4 ms │ 4 ms │ 5 ms  │ 6 ms │ 4.2 ms │ 1.51 ms │ 275 ms │
└─────────┴──────┴──────┴───────┴──────┴────────┴─────────┴────────┘
┌───────────┬─────────┬─────────┬─────────┬─────────┬───────────┬─────────┬─────────┐
│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg       │ Stdev   │ Min     │
├───────────┼─────────┼─────────┼─────────┼─────────┼───────────┼─────────┼─────────┤
│ Req/Sec   │ 19,503  │ 19,503  │ 21,839  │ 21,951  │ 21,748.27 │ 420.28  │ 19,495  │
├───────────┼─────────┼─────────┼─────────┼─────────┼───────────┼─────────┼─────────┤
│ Bytes/Sec │ 2.83 MB │ 2.83 MB │ 3.17 MB │ 3.18 MB │ 3.15 MB   │ 60.9 kB │ 2.83 MB │
└───────────┴─────────┴─────────┴─────────┴─────────┴───────────┴─────────┴─────────┘

Analysis

Adding middleware reduces throughput and increases latency for both frameworks. However, the performance gap remains substantial, with the framework still delivering ~4x higher throughput and ~4.5x lower latency than ExpressJS in this scenario.

Conclusion

This framework demonstrates remarkable performance, especially when handling high request loads or using middleware. While it’s an educational project inspired by ExpressJS and ElysiaJS, you might consider ElysiaJS for a more mature, production-ready solution.