From 3ee032c491c975858b3b10055bf04c6c02c3d13a Mon Sep 17 00:00:00 2001 From: Ryo Ota Date: Thu, 31 Mar 2022 06:43:23 +0900 Subject: [PATCH] docs: rewrite README.md for config v1 --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 69 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 25471463..2a654706 100644 --- a/README.md +++ b/README.md @@ -8,52 +8,98 @@ Rich [Piping Server](https://github.com/nwtgck/piping-server) Prepare `config.yaml` as follows. ```yaml -# config.yml -allowPaths: - - /0s6twklxkrcfs1u - - type: regexp - value: "/[abcd]+" -basicAuthUsers: +version: '1' +config_for: rich_piping_server + +# optional +basic_auth_users: - username: user1 password: pass1234 -rejection: nginx-down + +# optional +allow_paths: + # Allow transfer over "/0s6twklxkrcfs1u", not "/0s6twklxkrcfs1u/mypath" + - /0s6twklxkrcfs1u + # Allow transfer over the regular expression below + - regexp: ^/[abcd]+.*$ + # Simple at /mytop1/. Show version at /mytop1/version. Show help at /mytop1/help. Allow transfer /mytop1/mypath, /mytop1/hoge,.... + - index: /mytop1 + # Create multiple "index". + - index: /mytop2 + +# Respond a fake nginx 500 down page when rejected +rejection: fake_nginx_down + +# Close socket when rejected +#rejection: socket_close + +# Respond a fake nginx 500 down with version +#rejection: +# fake_nginx_down: +# nginx_version: 99.9.9 ``` -Run the server as follows. The config is hot-reloaded. +Run the server as follows. Hot reload of config is available. ```bash -npx nwtgck/rich-piping-server --config-yaml-path=config.yaml +npx nwtgck/rich-piping-server --config-path=config.yaml ``` -Sender and receiver can transfer over `http://localhost:8080/0s6twklxkrcfs1u` or `http://localhost:8080/aacacdb/path-you-want-to-use` with basic auth. If the path is not `/0s6twklxkrcfs1u`, not starting with `/aacacdb` or etc., requests are rejected. +Here are some example results of the server with the config. + +- transferable: `curl -u user1:pass1234 http://localhost:8080/0s6twklxkrcfs1u` +- transferable: `curl -u user1:pass1234 -T- http://localhost:8080/0s6twklxkrcfs1u` +- transferable: `curl -u user1:pass1234 http://localhost:8080/aabbaaccba` +- transferable: `curl -u user1:pass1234 http://localhost:8080/b` +- Web UI because of "index": `curl -u user1:pass1234 http://localhost:8080/mytop1/` +- version because of "index": `curl -u user1:pass1234 http://localhost:8080/mytop1/version` +- help because of "index": `curl -u user1:pass1234 http://localhost:8080/mytop1/help` +- transferable because of "index": `curl -u user1:pass1234 http://localhost:8080/mytop1/mypath` +- Web UI because of "index": `curl -u user1:pass1234 http://localhost:8080/mytop2/` +- reject because path is not allowed: `curl -u user1:pass1234 http://localhost:8080/` +- reject because of no basic auth: `curl http://localhost:8080/0s6twklxkrcfs1u` ### Run on Docker Prepare `./config.yaml` and run as follows on Docker. ```bash -docker run -p 8181:8080 -v $PWD/config.yaml:/config.yaml nwtgck/rich-piping-server --config-yaml-path=/config.yaml +docker run -p 8181:8080 -v $PWD/config.yaml:/config.yaml nwtgck/rich-piping-server --config-path=/config.yaml ``` The server runs on . -## Config syntax +## Config examples + +Config examples are found in the tests: + -The config YAML syntax is strictly typed with [io-ts](https://github.com/gcanti/io-ts). The definition of config is as follows: - +## Migration from legacy config -You can see other parameters and what fields are optional. +The command below prints new config. + +```bash +rich-piping-server --config-path=./config.yaml migrate-config +``` + +New Rich Piping Server supports the legacy config schema without migration. ## Options ``` +rich-piping-server [command] + +Commands: + rich-piping-server migrate-config Print migrated config + Options: - --help Show help [boolean] - --version Show version number [boolean] - --http-port Port of HTTP server [default: 8080] - --enable-https Enable HTTPS [default: false] - --https-port Port of HTTPS server [number] - --key-path Private key path [string] - --crt-path Certification path [string] - --config-yaml-path Config YAML path [string] [required] + --help Show help [boolean] + --version Show version number [boolean] + --host Bind address (e.g. 127.0.0.1, ::1) [string] + --http-port Port of HTTP server [default: 8080] + --enable-https Enable HTTPS [boolean] [default: false] + --https-port Port of HTTPS server [number] + --key-path Private key path [string] + --crt-path Certification path [string] + --config-path, --config-yaml-path Config YAML path [string] [required] ```