summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--Readme.md80
1 files changed, 42 insertions, 38 deletions
diff --git a/Readme.md b/Readme.md
index e7295c5..1960b51 100644
--- a/Readme.md
+++ b/Readme.md
@@ -7,15 +7,15 @@ errors (such as non-existent map entrypoints or missing asset files) and makes
suggestions to improve accessability.
It can also *adjust* maps — e.g. to automatically insert property values or help
-enforce an event's map policies (among other things, this is used to resolve
-special inter-assembly `world://` links).
+enforce an event's map policies (among other things, this was used to resolve
+special inter-assembly `world://` links at rc3).
`walint-mapserver` is a minimal implementation of a server that periodically
fetches, lints, and adjusts maps from a set of git repositories, writing them
-to a path that can then be served by a webserver. It can be used as a (very
-simple) replacement for rc3's hub and mapservice at smaller events — to get
-started, manually list all map repositories in `config.toml`, then visit
-`localhost:8080/admin/overview`.
+to a path that can then be served as static map files for a workadventure
+deployment. It can be used as a (very simple) replacement for rc3's hub and
+mapservice at smaller events — to get started, manually list all map
+repositories in `config.toml`, then visit `localhost:8080/admin/overview`.
## Installing
@@ -23,26 +23,28 @@ started, manually list all map repositories in `config.toml`, then visit
### From the CI pipeline
Gitlab [automatically builds a version](https://git.cccv.de/hub/walint/-/jobs)
-of `walint` each time something is pushed to this repository. The resulting
-binary should work fine on most linux systems, especially if they're vaguely
-debian-like.
+of `walint` each time something is pushed to the version of this repository
+kept at the CCCV infra. The resulting binary should work fine on most linux
+systems, especially if they're vaguely debian-like.
In case you get an incomprehensible or confusing error when executing it, try
-running `ldd walint` and see if anything is marked as not found, then install it.
+running `ldd walint` and see if anything is marked as not found, then install
+it.
### Build using stack
-This uses a lockfile to pin versions of dependencies (as well as `ghc`, the haskell
-compiler). You will need [the haskell stack](https://docs.haskellstack.org/en/stable/README/).
+This uses a lockfile to pin versions of dependencies (as well as `ghc`, the
+haskell compiler). You will need
+[the haskell stack](https://docs.haskellstack.org/en/stable/README/).
-Then just run
+Run
```
stack build
```
-If you lack `ghc` in the correct version and don't know how to install it, you can
-pass it `--install-ghc` to take care of that for you (note that on NixOS, `stack` may
+If you lack `ghc` and don't know how to install it, you can add `--install-ghc`,
+and `stack` will take care of that for you (note that on NixOS, `stack` may
use a fitting `ghc` derivation if it finds one, even without `--install-ghc`).
To install into your `$PATH`, use
@@ -57,9 +59,6 @@ Alternatively, run `walint` via stack:
stack run -- walint [options as normal]
```
-However, in this case stack will re-check files every time to ensure your build
-is up to date with the sources, increasing startup time.
-
### Build using cabal
You can, but probably should not. Beware of older Aeson versions!
@@ -78,8 +77,8 @@ walint --config-file config.json --repository path \
defaults to `main.json`
- `--lintLevel`: limit output only to messages that have at most the given
level. Valid levels are `Info`, `Suggestion`, `Warning`, `Forbidden`, `Error`,
- `Fatal`. Defaults to `Suggestion` if not given.
- - `--json`: print output as json instead of the normal more human-friendly format
+ `Fatal`. Defaults to `Suggestion`.
+ - `--json`: print output as json instead of the default human-friendly format
- `--pretty`: if used with `--json`, insert line breaks and indentation to make
the output more readable. Otherwise no effect.
- `--out path`: write the linted & adjusted repository to the given path. Any
@@ -102,40 +101,45 @@ have default values. In `config.json`, all possible keys are given.
Most options should be reasonably self-explanatory. Note that `MaxLintLevel`
differs from the option `--lintLevel`: the latter merely determines what is
*printed* (in case json output is not enabled), the former determines the
-maximum lint level allowed before the linter rejects the map and does not
-copy it to the path given to `--out`.
+maximum lint level allowed before the linter rejects the map and will refuse to
+copy it to the path given as `--out`.
### Uri Schemas
-`walint` supports (limited) rewriting of URIs contained in the map json via
-the `UriSchemas` option, which takes a map from uri schemas to a rule describing
-what to do with such links, depending on the scope in which they appear.
+`walint` supports (basic) rewriting of URIs contained in the map json via the
+`UriSchemas` option, which maps schemas to rules describing what to do with such
+links, depending on the scope in which they appear.
`walint` takes a very reductive view or URIs: `schema://domain/tail`
#### Rewrite Rules
-For now there are three types of such rules:
+For now there are four types of such rules:
- `schema: {"scope":[scopes]}`: if in a scope listed in `scopes`, allow any
links of the given `schema`
+ - `schema: {"scope":[scopes], "allowed":[allowed]}`: if in a scope listed in
+ `scopes`, only allow URIs whose domain occurs in `allowed`.
- `schema: {"scope":[scopes], "allowed":[allowed], "blocked":[blocked], "prefix":prefix}`:
- if in a scope listed in `scopes`, prefix any URIs of the given `schema` with
- the given `prefix`, unless the URI's domain occurs in `allowed` (in which case
- leave it untouched), or it occurs in `blocked`, in which
- case it will be rejected as a lint error.
- - `schema: {"scope":[scopes], "subst":{domain: prefix, ...}}`: if in a scope
- listed in `scopes` and given a URI with the domain `domain`, concatenate
- `prefix` with the tail of this URI.
+ if in a scope listed in `scopes`, allow URIs whose domain occurs in `allowed`,
+ disallow all whose domain occurs in `blocked`, and for all others, prefix
+ with the string given as `prefix`
+ - `schema: {"scope":[scopes], "substs":{domain: prefix, ...}}`: if in a
+ scope listed in `scopes` and given a URI with the domain `domain`,
+ concatenate `prefix` with the tail of this URI.
-In case an URI is encountered and there is no applicable rule, it will be rejected
-(note that this means you'll have to explicitly allow `https://` for links!)
+In case an URI is encountered and there is no applicable rule, it will be
+rejected (note that this means you'll have to explicitly allow `https://` for
+links!)
-There are currently three possible scopes: `map` applies to tiled map links
-(i.e. `exitUrl`), `website` to `openWebsite`, `audio` to `playAudio`.
+There are currently four scopes:
+ - `map` applies to tiled map links (i.e. `exitUrl`)
+ - `website` to `openWebsite`
+ - `audio` to `playAudio`
+ - `script` to scripts
## Output
-By default `walint` prints lints in a hopefully human-readable manner. Its exit
+By default `walint` prints lints in a (hopefully) human-readable format. Its exit
code will be 1 if the maximum lint level set in its config was exceeded, and 0
otherwise. Only in the latter case will it write out an adjusted map respository
to the path passed to `--out`. If the path given to `--out` already exists,