reserve
Version:
Lightweight http server statically configurable using regular expressions
127 lines (93 loc) • 5.16 kB
Markdown
<p align="center">
<img src="https://arnaudbuchholz.github.io/gfx/REserve.png" alt="REserve logo" width="300px"/>
</p>
# REserve 2️⃣
[](https://github.com/ArnaudBuchholz/reserve/actions/workflows/node.js.yml)
[](https://standardjs.com)
[](https://packagequality.com/#?package=reserve)
[](https://snyk.io/test/github/ArnaudBuchholz/reserve?targetFile=package.json)
[](https://www.npmjs.org/package/reserve)
[](https://packagephobia.now.sh/result?p=reserve)
[](https://packagephobia.com/result?p=reserve)
[](https://opensource.org/licenses/MIT)
[](https://app.fossa.com/projects/git%2Bgithub.com%2FArnaudBuchholz%2Freserve?ref=badge_shield)
[](https://github.com/ArnaudBuchholz/reserve/blob/main/docs/README.md)
[](https://github.com/ArnaudBuchholz/reserve/blob/main/reserve/CHANGELOG.md)
> 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp))* 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 :
```json
{
"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 :
```javascript
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](https://github.com/ArnaudBuchholz/reserve/blob/main/docs/serve.md) exposes a method similar to the [EventEmitter::on method](https://nodejs.org/api/events.html#emitteroneventname-listener) and throws events with parameters, see [Server events](https://github.com/ArnaudBuchholz/reserve/blob/main/docs/events.md).
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 :
```javascript
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)* :
```javascript
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](https://github.com/ArnaudBuchholz/reserve/tree/master/docs/README.md) to access documentation and articles about REserve.
[⚠️ From v1 to v2](https://github.com/ArnaudBuchholz/reserve/tree/master/docs/v1_to_v2.md)