reserve
TypeScript icon, indicating that this package has built-in type declarations

1.15.9 • Public • Published

REserve

RE duced levant verse proxy
gexp-based
useable
serve

Node.js CI Package Quality Known Vulnerabilities reserve reserve install size PackagePhobia MIT License FOSSA Status Documentation History

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

⚠️ This version of reserve is vulnerable to path traversal.

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. It also exposes a close method (returning a Promise) to shutdown the server.

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.

Dependencies (0)

    Dev Dependencies (21)

    Package Sidebar

    Install

    npm i reserve

    Weekly Downloads

    936

    Version

    1.15.9

    License

    MIT

    Unpacked Size

    68.1 kB

    Total Files

    34

    Last publish

    Collaborators

    • arnaud.buchholz