update readme

README

@@ -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/<number>
-Generate <number> strings from the chain
-
-NOTE: Number must be lower than 256

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/<number>`
+Generate `<number>` strings from the chain
+
+### `GET /get/sentance`
+Generate a single sentance from the chain
+
+### `GET /get/sentance/<number>`
+Generate `<number>` 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