Faster

A fast and optimized middleware server with an absurdly small amount of code (300 lines) built on top of Deno's native HTTP APIs with no dependencies. It also has a collection of useful middlewares: log file, serve static, CORS, session, rate limit, token, body parsers, redirect, proxy and handle upload. Fully compatible with Deno Deploy. In "README" there are examples of all the resources. Faster's ideology is: all you need is an optimized middleware manager, all other functionality is middleware.

Contents

Benchmarks

The middleware is built on top of Deno's native HTTP APIs, see the benchmarks ('hello word' server):

Machine: 8 GiB, Intel® Core™ i5-10210U CPU @ 2.11GHz × 4

method: autocannon -c 100 -d 40 -p 10 localhost:80. Deno v1.38.5, Ubuntu 22.04.3 LTS.

Framework Version Router? Results
Express 4.19.2 ✓ 167k requests in 40.11s, 29 MB read
Fastify 4.28.1 ✓ 1105k requests in 40.07s ,193 MB read
Oak 17.0.0 ✓ 260k requests in 40.09s, 45 MB read
Faster 11.3 ✓ 1432k requests in 40.17s, 250 MB read

Note that in addition to performance, Faster is a very complete framework considering its middleware collection.

Example

Defining routes

Static (/foo, /foo/bar)

Parameter (/:title, /books/:title, /books/:genre/:title)

Parameter w/ Suffix (/movies/:title.mp4, /movies/:title.(mp4|mov))

Optional Parameters (/:title?, /books/:title?, /books/:genre/:title?)

Wildcards (*, /books/*, /books/:genre/*)

POST read and return JSON

import { req, res, Server } from "https://deno.land/x/faster/mod.ts";
const server = new Server();
server.post(
  "/example_json",
  res("json"),
  req("json"),
  async (ctx: any, next: any) => {
    console.log(ctx.body);
    ctx.res.body = { msg: "json response example" };
    await next();
  },
);
await server.listen({ port: 80 });

GET return HTML

server.get(
  "/example_html",
  res("html"),
  async (ctx: any, next: any) => {
    ctx.res.body = `
      <!DOCTYPE html>
      <html>
        <head>
          <meta charset="utf-8">
          <title>title example</title>
        </head>
        </body>
          HTML body example
        <body>
      </html>
    `;
    await next();
  },
);

Get URL params

server.get(
  "/example_params/:ex1?foo=bar",
  async (ctx: any, next: any) => {
    console.log(ctx.params.ex1);
    console.log(ctx.url.searchParams.get("foo")); //you can explore the URL (ctx.url) object
    await next();
  },
);

Cookies

import {
  Cookie,
  deleteCookie,
  getCookies,
  getSetCookies,
  Server,
  setCookie,
} from "https://deno.land/x/faster/mod.ts"; //alias to deno std
server.get(
  "/cookies",
  async (ctx: any, next: any) => {
    setCookie(ctx.res.headers, { name: "user_name", value: "San" }); //explore interface 'Cookie' for more options
    deleteCookie(ctx.res.headers, "last_order");
    console.log(getCookies(ctx.req.headers));
    await next();
  },
);

Redirect

Use: ctx.redirect([status,] "/my_custom_url_or_path"). The default status is 302.

server.get(
  "/redirect_example",
  async (ctx: any, next: any) => {
    ctx.redirect(303, "/my_custom_url_or_path");
    await next();
  },
);
server.get(
  "/redirect_example",
  async (ctx: any, next: any) => {
    ctx.redirect("/my_custom_url_or_path");
    await next();
  },
);

Web Sockets

By default, the server will reject WebSocket connections to prevent vulnerabilities. To accept connections, you need to use the acceptOrRejectSocketConn function. This function should return an ID so you can retrieve the WebSocket later. If the function returns undefined, "" or null, 0, etc, the connection will be rejected. Here is a useful example of a function you can use:

server.acceptOrRejectSocketConn = async (ctx: Context) => {
  // Returning undefined, "" or null, 0, etc will reject the connection.
  return JSON.stringify(ctx.info.remoteAddr); //return ID
};

Now you can get the socket by ID:

server.openedSockets.get(yourId); //As in the example JSON.stringify(ctx.info.remoteAddr)

You can also receive WebSocket events:

server.onSocketMessage = async (id: string, socket: WebSocket, event: any) => {
  console.log(id);
  console.log(socket);
  console.log(event);
};
server.onSocketClosed = async (id: string, socket: WebSocket) => {
  console.log(id);
  console.log(socket);
};

Middleares

This project has a standard set of middleware useful for most cases.

Set Deno Kv and Deno Kv Fs

You need to launch Deno Kv and Deno Kv Fs as several middlewares depend on it. To do this, do:

const kv = await Deno.openKv(); //use your parameters here to launch a custom Deno.Kv
Server.setKv(kv);

Now, you can globally access instances in Server.kv and Server.kvFs. Deno KV file system (Server.kvFs) is compatible with Deno deploy. Saves files in 64kb chunks. You can organize files into directories. You can control the KB/s rate for saving and reading files, rate limit, user space limit and limit concurrent operations, useful for controlling uploads/downloads. Makes use of Web Streams API. See more at: https://github.com/hviana/deno_kv_fs

Logger

logger(salve: boolean = true, print: boolean = true)

If you haven't already and want to save the log, initialize Deno kv:

const kv = await Deno.openKv(); //use your parameters here to launch a custom Deno.Kv
Server.setKv(kv);

Example:

//You can also use useAtBeginning
server.use(logger()); //with default options, save and print are true

To return log data: await FasterLog.get(startMillis, endMillis)

To delete log data: await FasterLog.delete(startMillis, endMillis)

Body Parsers res and req

Example:

server.post(
  "/example_parsers",
  res("json"), //Response parser
  req("json"), //Request parser
  async (ctx: any, next: any) => {
    console.log(ctx.body); //the original (no parser) body is in ctx.req.body
    ctx.res.body = { msg: "json response example" };
    await next();
  },
);

The current supported options for "req" are: "arrayBuffer", "blob", "formData", "json", "text".

The current supported options for "res" are: "json", "html", "javascript".

If there are no parsers for your data, don't worry, you can handle the data manually, Ex:

server.post(
  "/custom_parse",
  async (ctx: any, next: any) => {
    ctx.res.headers.set(
      "Content-Type",
      "application/json",
    );
    const data = await exCustomParseBody(ctx.req.body); //do what you want with ctx.req.body
    ctx.res.body = JSON.stringify({ msg: "ok" }); // //ctx.res.body can also be other data types such as streams, bytes and etc.
    await next();
  },
);

Rate Limit

Example:

//You can also use useAtBeginning
server.use(rateLimit());

OPTIONS (with default values):

rateLimit({
  attempts: 30,
  interval: 10,
  maxTableSize: 100000,
  id: (ctx: Context) => JSON.stringify(ctx.info.remoteAddr),
});

Serve Static

Example (must end with "/*"):

server.get(
  "/pub/*",
  serveStatic("./pub"),
);

Set Cors

Example:

server.options("/example_cors", setCORS()); //enable pre-fligh request
server.get(
  "/example_cors",
  setCORS(),
  async (ctx, next) => {
    await next();
  },
);

You can pass valid hosts to cors function:

setCORS("http://my.custom.url:8080");

Token

This middleware is encapsulated in an entire static class. It uses Bearer Token and default options with the "HS256" algorithm, and generates a random secret when starting the application (you can also set a secret manually). Ex:

server.get(
  "/example_verify_token", //send token to server in Header => Authorization: Bearer TOKEN
  Token.middleware,
  async (ctx, next) => {
    console.log(ctx.extra.tokenPayload);
    console.log(ctx.extra.token);
    await next();
  },
);

Generate Token ex:

await Token.generate({ user_id: "172746" }, null); //null to never expire, this parameter defaults to "1h"

Set secret ex:

Token.setSecret("a3d2r366wgb3dh6yrwzw99kzx2"); //Do this at the beginning of your application

Get token payload out of middleware:

await Token.getPayload("YOUR_TOKEN_STRING"); //Ex: use for get token data from token string in URL parameter.

You can also use the static method Token.setConfigs.

Redirect Middleware

Ex: Use: redirect([status,] "/my_custom_url_or_path"). The default status is 302.

server.get(
  "/my_url_1",
  redirect(303, "/my_url_2"), //or the full url
);
server.get(
  "/my_url_1",
  redirect("/my_url_2"), //or the full url
);

Session

If you haven't already, initialize Deno kv:

const kv = await Deno.openKv(); //use your parameters here to launch a custom Deno.Kv
Server.setKv(kv);

Example

Ex:

//You can also use useAtBeginning
server.use(session());
//in routes:
server.get(
  "/session_example",
  async (ctx, next) => {
    console.log(ctx.extra.session); //get session data
    ctx.extra.session.value.foo = "bar"; //set session data (foo => "bar")
    await next();
  },
);

The default engine uses Deno KV and is optimized.

Absolute Expiration

The object in the Cache will expire on a certain date, from the moment of insertion of the object in the Cache, regardless of its use or not. The value (in minutes) 0 disables this type of expiration.

Sliding Expiration

The object in Cache will expire after the configured time, from the last request of the object in Cache (get or set). The value (in minutes) 0 disables this type of expiration.

Interface

If slidingExpiration and absoluteExpiration are 0, expiration is disabled. if absoluteExpiration and slidingExpiration are greater than 0 (enabled), absoluteExpiration cannot be less than slidingExpiration.

INTERFACE (SessionStorageEngine):

constructor(
  slidingExpiration: number = 0,
  absoluteExpiration: number = 0
)

DEFAULT VALUES:

session(engine: SessionStorageEngine = new KVStorageEngine()) //default is 60 min slidingExpiration

Proxy

Ex:

//You can also use useAtBeginning
server.use(proxy({ url: "https://my-url-example.com" }));

In routes:

server.get(
  "/proxy_example",
  async (ctx, next) => {
    console.log(ctx.req); //req has changed as it now points to the proxy
    console.log(ctx.res); //res has changed because now it has the proxy answer

    //OR if replaceReqAndRes = false
    console.log(ctx.extra.proxyReq);
    console.log(ctx.extra.proxyRes);

    await next();
  },
);

Or proxy in specific route:

server.get(
  "/proxy_example",
  proxy({
    url: "https://my-url-example.com/proxy_ex2",
    replaceProxyPath: false, //specific proxy route for the route "/proxy_example"
  }),
  async (ctx, next) => {
    console.log(ctx.req); //req has changed as it now points to the proxy
    console.log(ctx.res); //res has changed because now it has the proxy answer
    await next();
  },
);

Conditional proxy:

server.get(
  "/proxy_example",
  proxy({
    url: "https://my-url-example.com/proxy_ex3",
    condition: (ctx) => {
      if (ctx.url.searchParams.get("foo")) {
        return true;
      } else {
        return false;
      }
    },
  }),
  async (ctx, next) => {
    console.log(ctx.extra.proxied); //will be true if proxy condition is true
    console.log(ctx.req); //req has changed as it now points to the proxy
    console.log(ctx.res); //res has changed because now it has the proxy answer
    await next();
  },
);

OPTIONS (with default values):

proxy(url: string, replaceReqAndRes: true, replaceProxyPath: true, condition: : (ctx: Context) => true )

Do not use "res body parsers" with 'replaceReqAndRes: true' (default) !!!

If you don't use Request body information before the proxy or in your condition, don't use "req body parsers" as this will increase the processing cost !!!

Upload

If you haven't already, initialize Deno kv:

const kv = await Deno.openKv(); //use your parameters here to launch a custom Deno.Kv
Server.setKv(kv);

This middleware uses Deno KV file system (https://github.com/hviana/deno_kv_fs)

Upload usage

Ex:

//The route must end with *
//What is passed on * will be the file folder
.post("/files/*", upload(), async (ctx: any, next: any) => { ...
.get("/files/*", download(), async (ctx: any, next: any) => { ...

Ex (with custom options):

Dowload:

.post("/files/*", upload(
  { 
  allowedExtensions: async (ctx: Context) => ["jpg"],
  maxSizeBytes: async (ctx: Context) => (ctx.extra.user.isPremium() ? 1 : 0.1)*1024 * 1024 * 1024, //1GB or 100MB
  maxFileSizeBytes: async (ctx: Context) => (ctx.extra.user.isPremium() ? 1 : 0.1)*1024 * 1024 * 1024, //1GB or 100MB
  chunksPerSecond: async (ctx: Context) => (ctx.extra.user.isPremium() ? 10 : 1)/kvFs.getClientReqs(ctx.extra.user.id),
  maxClientIdConcurrentReqs: async (ctx: Context) => (ctx.extra.user.isPremium() ? 10 : 1),
  clientId: async (ctx: Context) => ctx.extra.user.id,
  validateAccess: (ctx: Context, path: string[]) => ctx.extra.user.hasDirAccess(path) ? true : false,
  }
), async (ctx: any, next: any) => { ...

Upload:

.get("/files/*", download(
  { 
  chunksPerSecond: async (ctx: Context) => (ctx.extra.user.isPremium() ? 10 : 1)/kvFs.getClientReqs(ctx.extra.user.id),
  maxClientIdConcurrentReqs: async (ctx: Context) => (ctx.extra.user.isPremium() ? 10 : 1),
  clientId: async (ctx: Context) => ctx.extra.user.id,
  validateAccess: (ctx: Context, path: string[]) => ctx.extra.user.hasDirAccess(path) ? true : false,
  maxDirEntriesPerSecond: async (ctx: Context) => (ctx.extra.user.isPremium() ? 1000 : 100),
  pagination: async (ctx: Context) => true,
  cursor: async (ctx: Context) => ctx.url.searchParams.get("cursor")
  }
))

Upload examples in frontend and backend

Request must contains a body with form type "multipart/form-data", and inputs with type="file".

Below an frontend example to work with AJAX, also accepting type="file" multiple:

var files = document.querySelector("#yourFormId input[type=file]").files;
var name = document.querySelector("#yourFormId input[type=file]").getAttribute(
  "name",
);

var form = new FormData();
for (var i = 0; i < files.length; i++) {
  form.append(`${name}_${i}`, files[i]);
}
var userId = 1; //example
var res = await fetch(`/files/${userId}`, { //Fetch API automatically puts the form in the format "multipart/form-data".
  method: "POST",
  body: form,
}).then((response) => response.json());
console.log(res);

In Deno (backend):

import {
  download,
  res,
  Server,
  upload,
} from "https://deno.land/x/faster/mod.ts";
const server = new Server();
server.post(
  "/files/*", //If you post to /files/a/b, a and b will be the files parent directories and will be included in the files path.
  res("json"),
  upload(), //Using default options. No controls.
  async (ctx: any, next: any) => {
    ctx.res.body = ctx.extra.uploadedFiles;
    await next();
  },
);
server.get(
  "/files/*", //You need to pass the URIComponent of the file here in the route, for example: /files/general/myFIle.xlsx
  download(), //Using default options. No controls.
);
server.get("/", res("html"), async (ctx: any, next: any) => {
  ctx.res.body = `
  <form id="yourFormId" enctype="multipart/form-data" action="/upload" method="post">
    <input type="file" name="file1" multiple><br>
    <input type="submit" value="Submit">
  </form>
    `;
  await next();
});
await server.listen({ port: 80 });

Organizing routes in files

It is possible to organize routes into files using native JavaScript resources. Example, main file:

import { Server } from "https://deno.land/x/faster/mod.ts";
import exampleRoutes from "./example_routes.ts";
const server = new Server();
exampleRoutes("example", server);
await server.listen({ port: 80 });

Secondary route file:

import { req, res, Server } from "https://deno.land/x/faster/mod.ts";
export default function exampleRoutes(namespace: string, server: Server) {
  server.post(
    `${namespace}/json`,
    res("json"),
    req("json"),
    async (ctx: any, next: any) => {
      console.log(ctx.body);
      ctx.res.body = { msg: "json response example" };
      await next();
    },
  );
  server.get(
    `${namespace}/html`,
    res("html"),
    async (ctx: any, next: any) => {
      ctx.res.body = `
            <!DOCTYPE html>
            <html>
              <head>
                <meta charset="utf-8">
                <title>title example</title>
              </head>
              </body>
                HTML body example
              <body>
            </html>
          `;
      await next();
    },
  );
}

All imports

import {
  Context,
  ContextResponse, //type
  Cookie, //type, alias to deno std
  deleteCookie, //alias to deno std
  DenoKvFs,
  DirList,
  download,
  FasterLog,
  File,
  FileStatus,
  getCookies, //alias to deno std
  getSetCookies, //alias to deno std
  KVStorageEngine,
  logger,
  NextFunc, //type
  Params, //type
  parse,
  ProcessorFunc, //type
  proxy,
  rateLimit,
  ReadOptions,
  redirect,
  req,
  res,
  Route, //type
  RouteFn, //type
  SaveOptions,
  Server,
  serveStatic,
  Session, //type
  session,
  SessionStorageEngine,
  setCookie, //alias to deno std
  setCORS,
  Token,
  upload,
} from "https://deno.land/x/faster/mod.ts";

Example Deploy

Example of depoly application "my-deno-app" in ubuntu environment. Change the "my-deno-app" and the directories to yours.

Create service

Create run script ("run-server.sh") in your application folder with the content:

#!/bin/bash
/home/ubuntu/.deno/bin/deno run --allow-all --unstable-kv /home/ubuntu/my-deno-app/app.ts

Give permission to the script:

chmod +x run-server.sh

Create service files:

sudo touch /etc/systemd/system/my-deno-app.service
sudo nano /etc/systemd/system/my-deno-app.service

In "my-deno-app".service (change the "Description", "WorkingDirectory" and "ExecStart" to yours):

[Unit]
Description=My Deno App

[Service]
WorkingDirectory=/home/ubuntu/my-deno-app
ExecStart=/home/ubuntu/my-deno-app/run-server.sh
TimeoutSec=30
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

If your application needs to wait for another service to start, such as the mongodb database, you can use the ´[Unit]´ section like this:

[Unit]
Description=My Deno App
After=mongod.service

Enable the "my-deno-app" service:

sudo systemctl enable my-deno-app.service

To start and stop the "my-deno-app" service:

sudo service my-deno-app stop
sudo service my-deno-app start

See log:

journalctl -u my-deno-app.service --since=today -e

Configure HTTPS

Install certbot:

sudo apt install certbot

Generate certificates (port 80 needs to be free):

sudo certbot certonly --standalone

In step:

"Please enter the domain name(s) you would like on your certificate (comma and/or space separated) (Enter 'c' to cancel):"

Insert domains and subdomains, example: yourdomain.link www.yourdomain.link

To run your application on https (Change "yourdomain.link" to your domain):

await server.listen({
  port: 443,
  cert: await Deno.readTextFile(
    "/etc/letsencrypt/live/yourdomain.link/fullchain.pem",
  ),
  key: await Deno.readTextFile(
    "/etc/letsencrypt/live/yourdomain.link/privkey.pem",
  ),
});

The certificate is valid for a short period. Set crontab to update automatically. The command 'sudo crontab' opens roots crontab, all commands are executed as sudo. Do like this:

sudo crontab -e

Add to the end of the file (to check and renew if necessary every 12 hours - port 80 needs to be free):

0 */12 * * * certbot -q renew --standalone --preferred-challenges=http

Or also to check every 7 days (port 80 needs to be free):

0 0 * * 0 certbot -q renew --standalone --preferred-challenges=http

See also the complete framework with faster and React

https://github.com/hviana/faster_react

About

Author: Henrique Emanoel Viana, a Brazilian computer scientist, enthusiast of web technologies, cel: +55 (41) 99999-4664. URL: https://sites.google.com/view/henriqueviana

Improvements and suggestions are welcome!