REserve 2️⃣

A lightweight web server configurable with regular expressions. It can also be embedded and extended. The name comes from the combination of RE for regular expressions and serve.

🍁 Rational

Initially started to build a local development environment where static files are served and resources can be fetched from remote repositories, this tool is versatile and can support different scenarios :

• A simple web server,
• A reverse proxy,
• A server that aggregates several sources,
• ...

By defining an array of mappings, one can decide how the server will process the incoming requests. Each mapping associates matching criteria (method selection, url matching using regular expression) to a handler that will answer the request.

The configuration syntax favors simplicity without dropping flexibility.

For instance, the definition of a server that exposes files of the current directory but forbids access to the directory private consists in :

{
  "port": 8080,
  "mappings": [{
    "match": "^/private/",
    "status": 403
  }, {
    "match": "^/(.*)",
    "file": "./$1"
  }, {
    "status": 404
  }]
}

Example of reserve.json configuration file

💿 Usage

Command line

The package declares the executable reserve :

• By default, it will look for a file named reserve.json in the current working directory
• One or more configuration files name can be specified using --config <file names separated by ,>

Embedded

The server can be embedded in an application using the serve export :

const { serve } = require('reserve')

serve({
  port: 8080,
  mappings: [{
    match: /^\/(.*)/,
    file: '$1'
  }, {
    "status": 404
  }]
})
  .on('ready', ({ url }) => {
    console.log(`Server running at ${url}`)
  })

Embedding reserve in a custom application (CommonJS)

The resulting object exposes a method similar to the EventEmitter::on method and throws events with parameters, see Server events. It also exposes a close method (returning a Promise resolved when all pending requests are completed) to shutdown the server.

The package also gives access to the configuration reader :

import { read, serve } from 'reserve'

read('reserve.json')
  .then(configuration =>
    serve(configuration)
      .on('ready', ({ url }) => {
        console.log(`Server running at ${url}`)
      })
  )

Embedding reserve in a custom application (ESM)

And a default log output (verbose mode will dump all redirections) :

import { log, read, serve } from 'reserve'

read('reserve.json')
  .then(configuration =>
    log(serve(configuration), /*verbose: */ true)
  )

Embedding reserve with the default logger (ESM)

⚖️ License

The package is licensed MIT and has no dependencies.

📚 Documentation

Go to this page to access documentation and articles about REserve.

⚠️ From v1 to v2