REserve

RE	duced levant verse proxy gexp-based useable serve

A lightweight web server statically configurable with regular expressions. It can also be embedded and extended.

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 to an existing server
• A server that aggregates several sources
• ...

By defining an array of mappings, one can decide how the server will process the 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"
  }]
}

Usage

npm start

• Install the package with npm install reserve (you decide if you want to save it as development dependency or not)
• You may create a start script in package.json :

{
  "scripts": {
    "start": "reserve"
  }
}

• By default, it will look for a file named reserve.json in the current working directory
• A configuration file name can be specified using --config <file name>, for instance :

{
  "scripts": {
    "start": "reserve",
    "start-dev": "reserve --config reserve-dev.json"
  }
}

Global

• Install the package with npm install reserve --global
• Run reserve
  • By default, it will look for a file named reserve.json in the current working directory
  • A configuration file name can be specified using --config <file name>

NOTE : if process.send is defined, REserve will notify the parent process when the server is ready by sending the message 'ready'.

Embedded

It is possible to implement the server in an application using the serve export :

const path = require('path')
const { check, serve } = require('reserve')
check({
  port: 8080,
  mappings: [{
    match: /^\/(.*)/,
    file: path.join(__dirname, '$1')
  }]
})
  .then(configuration => {
    serve(configuration)
      .on('ready', ({ url }) => {
        console.log(`Server running at ${url}`)
      })
  })

The resulting object implements the EventEmitter class and throws events with parameters, see Server events.

The package also gives access to the configuration reader :

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

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

const path = require('path')
const { log, read, serve } = require('reserve')
read('reserve.json')
  .then(configuration => {
    log(serve(configuration), /*verbose: */ true)
  })

NOTE : log is using colors if installed.

Complete documentation

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