Skip to content

GaelGirodon/liege

Repository files navigation

Liège

release license build tests coverage docker

HTTP stub server from plain files

About

Liège is a static file server for tests with some special features to easily setup a stub server without requiring too much configuration:

  • Handle all HTTP methods (static file servers usually handle GET/HEAD methods only)
  • Allow customizing request routing and response using the file name without requiring a configuration file
  • Send the request body back in an HTTP header
  • Handle index files

Usage

liege [flags] <root-dir>

Arguments

Argument Description Environment variable Configuration
<root-dir> Path to the server root directory LIEGE_ROOT root
-p <port> Port to listen on (default 3000) LIEGE_PORT
-c <cert> Path to the TLS certificate PEM file LIEGE_CERT
-k <key> Path to the TLS private key PEM file LIEGE_KEY
-l <lat> Simulated response latency in ms LIEGE_LATENCY latency
-v Print the version number and exit
-h Print the help message and exit

Example

$ liege ./data/
_________ __   _________________
________ / /  /  _/ __/ ___/ __/
_______ / /___/ // _// (_ / _/
______ /____/___/___/\___/___/

HTTP server started on port 3000

Configuration

Given the following file tree:

data/ -> server root directory
 |-- items/
 |    |-- index.json
 |    |-- index__qs.json
 |    |-- 1__GET.json
 |-- admin/
 |    |-- index__403_l50 (empty file)

The server will handle the following routes:

Method Paths Query Response Served file Latency
* /items
/items/index
/items/index.json
200 items/index.json ~ 0 ms
* /items
/items/index
/items/index.json
s[=*] 200 items/index__qs.json ~ 0 ms
GET /items/1
/items/1.json
200 items/1__GET.json ~ 0 ms
* /admin
/admin/index
403 ~ 50 ms

And send the following response with an optional additional latency:

  • Status code: 200 (default) or a custom code
  • Headers:
    • Content-Type: determined from file content and extension, e.g. application/json; charset=utf-8
    • X-Request-Body: base64 encoded request body (only if body size <= 4 KB)
  • Body: stub file contents

Routing and response can be customized using the following file name syntax:

<path>[__<options>][.<ext>]
Param Description
path File name, used in the URL path
options Additional routing and response configuration
ext File extension, helps to determine content type

__<options> can be used to further customize request routing and response by appending a list of options, prefixed by __ and separated by _, at the end of the file name:

Syntax Description Default Examples
<method> HTTP method * GET
q<key>[=<val>] Required query parameter(s) qerror=1
<code> Custom HTTP response status code 200 401
l<x>[-<y>] Simulated response latency in ms 0 l40, l50-90

For example, the content of a file named page__GET_qsearch_403_l250 will be sent with a 403 status code and at least 250 ms latency only for GET requests on /page URL with a search query parameter.

The latency can be constant (<x>) or random between a range (<x>-<y>) and can be defined globally (using the CLI or the environment variable) and at the route level using the file name. The same syntax (<x>[-<y>]) is used in both cases. Latency defined at the file level overrides globally defined latency unless the latter is set to -1 which totally disables latency.

On start-up, the server loads stub files in memory and build routes. To reload stub files from the root directory and update routes, call the refresh endpoint.

Management endpoints

The server provides the following management endpoints:

Method Path Response Description
GET /_liege/config 200 Get configuration
PUT /_liege/config 204 Update configuration
POST /_liege/refresh 204 Reload stub files
GET /_liege/routes 200 Get available routes

TLS setup

Generate a self-signed X.509 TLS certificate or obtain a certificate from a CA, and start the server with -c and -k flags:

$ liege -c cert.pem -k key.pem ./data/

License

Liège is licensed under the GNU General Public License.