reserve v1.15.9

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"
  }]
}

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 ,>

NOTE : if process.send is available, REserve notifies the parent process when the server is ready by sending the message 'ready'.

Embedded

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

const { serve } = require('reserve')

serve({
  port: 8080,
  mappings: [{
    match: /^\/(.*)/,
    file: '$1'
  }]
})
  .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