Skip to content

Latest commit

 

History

History
122 lines (85 loc) · 4.7 KB

README.md

File metadata and controls

122 lines (85 loc) · 4.7 KB

REserve logo

REserve 2️⃣ Documentation

Important

Migration guide From v1 to v2

✅ Configuration

There are two ways to use REserve :

  • Run as a standalone command line with a configuration file (default name is reserve.json)
{
  "port": 8080,
  "mappings": [{
    "match": "^/private/",
    "status": 403
  }, {
    "match": "^/(.*)",
    "file": "./$1"
  }, {
    "status": 404
  }]
}

Example of reserve.json configuration file

Note

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

  • Embed with its configuration in a custom application
import { serve, log } from 'reserve'

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

Example of reserve being embedded in an application

In both cases, the configuration must comply with the properties and mappings documented here.

Tip

tips & tricks

⚙ Handlers

REserve is delivered with the following default handlers :

  • file : to serve resources from the file system
  • status : to end response with a specific status
  • url : to serve resources from a web address
  • custom : to enable custom coding
  • use : to integrate packaged middlewares (express)

Other additional handlers can be installed separately and plugged through the handlers configuration property. If you plan to build your own handler, here is what you need to know.

⚡ Server events

The REserve server object implements an interface that mimics the EventEmitter::on method and, during execution, it triggers events with parameters to notify any listener of its activity.

📦 Exports

REserve exports methods and helpers to simplify implementations :

  • serve : to start the server
  • read : to read a configuration file, supports extends
  • check : to check a configuration
  • log : to handle and output server logs
  • interpolate : to interpolate values in a string or an object
  • body : to read a request body
  • send : to build a response
  • capture : to copy the response stream to another stream (for instance: to create a cache)
  • punycache : a minimalist cache implementation

🧪 Testing / Mocking

REserve includes a mocking environment to ease the tests. It takes the configuration and returns a fake server object augmented with a request method to simulate incoming requests.

⌛ Version history

Here is the history of versions with their associated changes.

📚 Articles

Rational

Sometimes, a simple idea leads to very interesting projects. This article explains the creation of REserve best described as a lightweight web server statically configurable with regular expressions that can also be embedded and extended.

Technical details

Based on a clean concept, the development of REserve follows a simple architecture that enables flexibility and extensibility. This article provides keys to understand the modular structure of the implementation.

Serving an OpenUI5 application

The best way to explain what REserve can do is to demonstrate some of its features through a concrete use case. This article illustrates how one can quickly setup a server to facilitate the execution of OpenUI5 applications.

Cache and Proxy

With version 1.8.0, REserve offers the capture helper that enables the copy of the response content while processing a request. In this article, an example will be presented in two different flavors to illustrate the new possibilities introduced by this tool.

Performances

A benchmark realized to compare performances of express, koa, fastify and REserve.