diff options
Diffstat (limited to '')
| -rw-r--r-- | Readme.md | 80 |
1 files changed, 42 insertions, 38 deletions
@@ -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, |