Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gaelgirodon/liege
HTTP stub server from plain files
https://github.com/gaelgirodon/liege
api http http-server json mock mock-api mock-data mock-server mocking mocking-server mocking-utility prototyping rest-api server stub stub-server stubbing
Last synced: 1 day ago
JSON representation
HTTP stub server from plain files
- Host: GitHub
- URL: https://github.com/gaelgirodon/liege
- Owner: GaelGirodon
- License: gpl-3.0
- Created: 2020-09-26T21:38:16.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T22:05:30.000Z (8 months ago)
- Last Synced: 2024-04-02T23:23:40.809Z (8 months ago)
- Topics: api, http, http-server, json, mock, mock-api, mock-data, mock-server, mocking, mocking-server, mocking-utility, prototyping, rest-api, server, stub, stub-server, stubbing
- Language: Go
- Homepage:
- Size: 54.7 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# _Liège_
[](https://github.com/GaelGirodon/liege/releases/latest)
[](./LICENSE)
[](https://github.com/GaelGirodon/liege/actions/workflows/build.yml)
[](https://github.com/GaelGirodon/liege/actions/workflows/build.yml)
[](https://github.com/GaelGirodon/liege/actions/workflows/build.yml)
[](https://hub.docker.com/r/gaelgirodon/liege)
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
```shell
liege [flags]
```
### Arguments
| Argument | Description | Environment variable | Configuration |
| ------------ | ------------------------------------ | -------------------- | ------------- |
| `` | Path to the server root directory | `LIEGE_ROOT` | `root` |
| `-p ` | Port to listen on (default `3000`) | `LIEGE_PORT` |
| `-c ` | Path to the TLS certificate PEM file | `LIEGE_CERT` |
| `-k ` | Path to the TLS private key PEM file | `LIEGE_KEY` |
| `-l ` | Simulated response latency in ms | `LIEGE_LATENCY` | `latency` |
| `-v` | Print the version number and exit |
| `-h` | Print the help message and exit |
### Example
```shell
$ liege ./data/
_________ __ _________________
________ / / / _/ __/ ___/ __/
_______ / /___/ // _// (_ / _/
______ /____/___/___/\___/___/
HTTP server started on port 3000
```
### Configuration
Given the following file tree:
```text
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:
```text
[__][.]
```
| Param | Description |
| --------- | ----------------------------------------------- |
| `path` | File name, used in the URL path |
| `options` | Additional routing and response configuration |
| `ext` | File extension, helps to determine content type |
`__` 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 |
| ---------------- | -------------------------------- | ------- | --------------- |
| `` | HTTP method | `*` | `GET` |
| `q[=]` | Required query parameter(s) | | `qerror=1` |
| `` | Custom HTTP response status code | `200` | `401` |
| `l[-]` | 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 (``) or random between a range (`-`) and
can be defined globally (using the CLI or the environment variable) and at the
route level using the file name. The same syntax (`[-]`) 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:
```shell
$ liege -c cert.pem -k key.pem ./data/
```
## License
_Liège_ is licensed under the GNU General Public License.