From 053f41ee50900786cfa55a63ba4da5092ba9c928 Mon Sep 17 00:00:00 2001 From: Avril Date: Mon, 12 Oct 2020 04:48:30 +0100 Subject: [PATCH] update readme --- README | 16 ------------ README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 16 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index c17a163..0000000 --- a/README +++ /dev/null @@ -1,16 +0,0 @@ -HTTP server connecting to a Markov chain - -Feeding: -# PUT /put -Request body is fed to the chain - -NOTE: Strings fed to the chain must be valid UTF-8 and below 16 KB in size - -Generating: -# GET /get -Generate a string from the chain - -# GET /get/ -Generate strings from the chain - -NOTE: Number must be lower than 256 \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..e550035 --- /dev/null +++ b/README.md @@ -0,0 +1,75 @@ +# genmarkov +HTTP server connecting to a Markov chain + +# Build requirements +Unix & Rust nightly are currently requirements to build, for now. + +# Configuration +When ran with no arguments, `markov` will attempt to load the config file at `markov.toml`. If it does not exist, it will use the default configuration. (On debug builds, it will also create the default `markov.toml`.) + +An example default configuration file is provided at [./markov.toml](markov.toml). + +When ran with an argument specifying the config file however, it will attempt to load that. If it fails to load the file, the default will be used. + +## Config file entries +| Name | Description | Default | Optional | +|-------------------------|---------------------------------------------------------|------------------|----------| +| `bindpoint` | Address or Unix domain socket for the server to bind to | `127.0.0.1:8001` | No | +| `file` | File to save and load the chain from | `chain.dat` | No | +| `max_content_length` | Max request body length to allow | `4194304` (4MB) | No | +| `max_gen_size` | Max number of strings for a request to generate at once | `256` | No | +| `save_interval_secs` | Number of seconds to ensure waiting before saving chain | `2` | Yes | +| `trust_x_forwarded_for` | Trust the `X-Forwarded-For` HTTP header | `false` | No | +| `filter` | Remove characters from incoming and/or outgoing text | None | Yes | + +### AF_UNIX note +When binding to a Unix domain socket, prefix the path with `unix:/` (e.g. `unix://var/markov.socket`) +The server will not attempt to remove already existing sockets at the path, so ensure there isn't one before launching. + +## Logging + +Set the `RUST_LOG` environment variable to one of the following to switch runtime logging levels. +* `trace` - Most verbose +* `debug` - Verbose +* `info` - Show input and output to/from the chain and requests +* `warn` - Only show warnings (default) +* `error` - Only show errors + +## Signals +On Unix systems at runtime, some signals are trapped: + +| Signal | Description | +|-----------|------------------------------------------------------------------------| +| `SIGUSR1` | Immediately save the chain | +| `SIGUSR2` | Immediately load the chain | +| `SIGQUIT` | Ensure the chain is properly saved and then immediately call `abort()` | +| `SIGINT` | Perform a full graceful shutdown | + +# Usage +The server exposes several paths for access of the chain + +## Feeding +### `PUT /put` +Request body is fed to the chain + +#### NOTE +Strings fed to the chain must be valid UTF-8 and a size below the value specified in the config file. + +## Generating +### `GET /get` +Generate a string from the chain + +### `GET /get/` +Generate `` strings from the chain + +### `GET /get/sentance` +Generate a single sentance from the chain + +### `GET /get/sentance/` +Generate `` sentances from the chain + +#### NOTE +Number of strings/sentances must be lower than the value specified in the config file. + +# License +GPL'd with <3