@egomobile/http-server

A very fast alternative HTTP server to Express, with simple routing and middleware support, that is compatible with Node.js 18 or later.

Table of contents

• Install
• Usage
  • Quick example
  • Middlewares
  • Controllers
  • Error handling
    • Pretty error pages
  • Testing
• Benchmarks
• Credits
• Documentation
• See also

Install [↑]

Execute the following command from your project folder, where your package.json file is stored:

1npm install --save @egomobile/http-server

If you want to lookup types, also install the Node Types:

1npm install --save-dev @types/node

Usage [↑]

Quick example [↑]

1import createServer, { buffer, params, query } from "@egomobile/http-server";
2
3async function main() {
4  const app = createServer();
5
6  // POST request for / route
7  // that uses the middleware buffer(), which loads the
8  // whole request body with a limit of 128 MB by default
9  // and writes the data to 'body' prop of 'request' object
10  // as Buffer
11  app.post("/", [buffer()], async (request, response) => {
12    const name: string = request.body!.toString("utf8");
13
14    response.write("Hello: " + name);
15    // no response.end() is required here
16  });
17
18  // parameters require a special path validator here
19  // s. https://github.com/lukeed/regexparam
20  // for more information about the string format
21  app.get(params("/foo/:bar/baz"), async (request, response) => {
22    response.write("BAR: " + request.params!.bar);
23  });
24
25  // parse query parameters from URL
26  // and write them to 'query' prop of 'request' object
27  app.get("/foo", [query()], async (request, response) => {
28    // request.query => https://nodejs.org/api/url.html#class-urlsearchparams
29
30    response.write(" BAR: " + request.query!.get("bar"));
31    response.write(" BAZ: " + request.query!.get("baz"));
32  });
33
34  await app.listen();
35  console.log(`Server now running on port ${app.port} ...`);
36}
37
38main().catch(console.error);

Middlewares [↑]

To enhance the functionality of your handlers, you can setup global or route specific middlewares.

For more details, have a look at the wiki page.

Controllers [↑]

The module provides tools, like decorators, functions and classes, that helps to setup routes and their behavior on a quite simple and high level.

Have a look at the wiki page for detailed information.

Error handling [↑]

1import createServer from "@egomobile/http-server";
2
3async function main() {
4  // ...
5
6  // custom error handler
7  app.setErrorHandler(async (error, request, response) => {
8    const errorMessage = Buffer.from("SERVER ERROR: " + String(error), "utf8");
9
10    if (!response.headersSend) {
11      response.writeHead(400, {
12        "Content-Length": String(errorMessage.length),
13      });
14    }
15
16    response.write(errorMessage);
17    response.end();
18  });
19
20  // custom 404 handler
21  app.setNotFoundHandler(async (request, response) => {
22    const notFoundMessage = Buffer.from(`${request.url} not found!`, "utf8");
23
24    if (!response.headersSend) {
25      response.writeHead(404, {
26        "Content-Length": String(notFoundMessage.length),
27      });
28    }
29
30    response.write(notFoundMessage);
31    response.end();
32  });
33
34  app.get("/", async (request, response) => {
35    throw new Error("Something went wrong!");
36  });
37
38  // ...
39}
40
41main().catch(console.error);

Pretty error pages [↑]

A nice example is, to use Youch! by Poppinss.

It prints pretty error pages in the browser:

1import createServer, { prettyErrors } from "@egomobile/http-server";
2import youch from "youch";
3
4async function main() {
5  // ...
6
7  app.setErrorHandler(async (error, request, response) => {
8    const html = Buffer.from(await new youch(error, request).toHTML(), "utf8");
9
10    if (!response.headersSent) {
11      response.writeHead(500, {
12        "Content-Type": "text/html; charset=UTF-8",
13        "Content-Length": String(html.length),
14      });
15    }
16
17    response.end(html);
18  });
19
20  app.get("/", async (request, response) => {
21    throw new Error("Oops! Something went wrong!");
22  });
23
24  // ...
25}
26
27main().catch(console.error);

A possible result could be:

Testing [↑]

With decorators @Describe() and @It(), you can write automatic (unit-)tests, realized by any framework you want.

This example shows, how to implement tests with SuperTest (if you want to see a more detailed description of this feature, you can visit the wiki page):

Controller [↑]

1import {
2  Controller,
3  ControllerBase,
4  Describe,
5  GET,
6  IHttpRequest,
7  IHttpResponse,
8  It,
9} from "@egomobile/http-server";
10
11@Controller()
12@Describe("My controller")
13export default class MyController extends ControllerBase {
14  @GET("/foo/:bar")
15  @It(
16    "should return '{{body}}' in body with status {{status}} when submitting parameter {{parameter:bar}}",
17    {
18      expectations: {
19        body: "BUZZ",
20        status: 202,
21      },
22      parameters: {
23        bar: "buzz",
24      },
25    }
26  )
27  async index(request: IHttpRequest, response: IHttpResponse) {
28    response.writeHead(202);
29    response.write(request.params!.bar.toUpperCase());
30  }
31}

Initialization [↑]

1import assert from "assert";
2import supertest from "supertest";
3import { createServer } from "@egomobile/http-server";
4
5const app = createServer();
6
7// event, that is executed, if a test is requested
8app.on("test", async (context) => {
9  const {
10    body,
11    description,
12    escapedRoute,
13    expectations,
14    group,
15    headers,
16    httpMethod,
17    server,
18  } = context;
19
20  try {
21    process.stdout.write(`Running test [${group}] '${description}' ... `);
22
23    // prepare request ...
24    // HTTP method ...
25    let request = supertest(server)[httpMethod](escapedRoute);
26    // request headers ...
27    for (const [headerName, headerValue] of Object.entries(headers)) {
28      request = request.set(headerName, headerValue);
29    }
30
31    // send it
32    const response = await request.send(body);
33
34    assert.strictEqual(response.statusCode, expectations.status);
35
36    // maybe some more code checking headers and
37    // body data from `expectations` ...
38
39    process.stdout.write(`✅\n`);
40  } catch (error) {
41    process.stdout.write(`❌: ${error}\n`);
42  }
43});
44
45// run tests
46await app.test();
47
48// alternative:
49//
50// if you set `EGO_RUN_SETUP` to a truthy value like `1`
51// the server does not start listening, instead it simply
52// runs `app.test()`
53//
54// await app.listen();

Benchmarks [↑]

	Express	fastify	polka	@egomobile/http-server
Express	-	93%	39%	30% 🐌
fastify	107%	-	43%	32% 🐢
polka	256%	238%	-	76% 🐇
@egomobile/http-server	337% 🚀🚀🚀	314% 🚀🚀	132% 🚀	-

The following benchmarks were made with wrk on the following machine, running Node v16.13.2:

Machine:

• MacBook Pro (16", 2021)
• CPU: Apple M1 Max
• Memory: 64 GB
• OS: MacOS 12.1

Command: wrk -t8 -c100 -d30s http://localhost:3000/user/123

Express:
=============
Running 30s test @ http://localhost:3000/user/123
  8 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     3.56ms  674.79us  14.59ms   90.47%
    Req/Sec     3.39k   224.41     5.11k    75.04%
  809164 requests in 30.03s, 118.84MB read
Requests/sec:  26947.30
Transfer/sec:      3.96MB


Fastify:
=============
Running 30s test @ http://localhost:3000/user/123
  8 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     3.32ms    0.95ms  19.41ms   85.25%
    Req/Sec     3.64k   280.76     4.87k    76.38%
  869871 requests in 30.03s, 142.69MB read
Requests/sec:  28971.44
Transfer/sec:      4.75MB


Polka:
===========
Running 30s test @ http://localhost:3000/user/123
  8 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.39ms  289.29us  13.20ms   91.15%
    Req/Sec     8.66k     1.26k   10.67k    59.55%
  2074873 requests in 30.10s, 259.22MB read
Requests/sec:  68930.81
Transfer/sec:      8.61MB


@egomobile/http-server:
============================
Running 30s test @ http://localhost:3000/user/123
  8 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.05ms  220.64us  13.11ms   85.16%
    Req/Sec    11.44k     1.39k   18.48k    81.16%
  2737095 requests in 30.10s, 341.95MB read
Requests/sec:  90922.13
Transfer/sec:     11.36MB

Here is the test code, used recording the benchmarks.

Credits [↑]

The module makes use of:

• Ajv
• Filtrex by Michal Grňo
• joi by Sideway Inc.
• js-yaml by Nodeca
• minimatch by isaacs
• regexparam by Luke Edwards
• Swagger UI and @open-api

Documentation [↑]

The API documentation can be found here.

See also [↑]

• @egomobile/api-utils - Extensions for this module, helping realizing REST APIs