reverse-proxy-middleware 0.0.145 → 0.0.147

package/readme.md

@@ -7,11 +7,13 @@ License
 -------
 
 This library written by Torben Sickert stands under a creative commons naming
-3.0 unported license. See https://creativecommons.org/licenses/by/3.0/deed.de
+4.0 international license.
+See https://creativecommons.org/licenses/by/4.0/deed.de
 endregion -->
 
 <!--|deDE:Projektstatus-->
-Project Status
+<!--|frFR:Statut du projet-->
+Project status
 --------------
 
 [![npm](https://img.shields.io/npm/v/reverse-proxy-middleware?color=%23d55e5d&label=npm%20package%20version&logoColor=%23d55e5d&style=for-the-badge)](https://www.npmjs.com/package/reverse-proxy-middleware)
@@ -31,16 +33,38 @@ Project Status
 [![deploy web documentation](https://img.shields.io/github/actions/workflow/status/thaibault/reverse-proxy-middleware/deploy-web-documentation.yaml?label=deploy%20web%20documentation&style=for-the-badge)](https://github.com/thaibault/reverse-proxy-middleware/actions/workflows/deploy-web-documentation.yaml)
 [![web documentation](https://img.shields.io/website-up-down-green-red/https/tsickert.com/reverse-proxy-middleware.svg?label=web-documentation&style=for-the-badge)](https://tsickert.com/reverse-proxy-middleware)
 
-<!--|deDE:Verwendung-->
+<!--|deDE:Einsatzmöglichkeiten-->
+<!--|frFR:Cas d'utilisation-->
 Use case
 --------
 
-Easy and dynamically configurable reverse proxy. This tool can act as a
-middleware to check incoming requests via external bot filtering services such
-as ReCaptcha or friendlycaptcha.
-Adding state via session token with external authentication apis is possible as
-applying any external api given data to the incoming and conditionally
-forwarded requests.
+A small reverse proxy configured with a single JSON file. Each incoming request
+is passed on to one of the configured backends ("forwarders"). Before that, the
+proxy can ask third party services ("state APIs"), e.g. a bot filter like
+reCAPTCHA or friendlycaptcha or an authentication service, and answer the
+request itself depending on their responses. Request and response headers can
+be rewritten on the way through. All decisions are short JavaScript
+expressions inside the configuration.
+<!--deDE:
+    Ein kleiner Reverse-Proxy, der über eine einzige JSON-Datei konfiguriert
+    wird. Jede eingehende Anfrage wird an eines der konfigurierten Backends
+    ("Forwarder") weitergereicht. Vorher kann der Proxy Dienste von
+    Drittanbietern ("State-APIs") befragen, z. B. einen Bot-Filter wie
+    reCAPTCHA oder friendlycaptcha oder einen Authentifizierungsdienst, und
+    die Anfrage abhängig von deren Antworten selbst beantworten. Anfrage- und
+    Antwort-Header lassen sich unterwegs umschreiben. Alle Entscheidungen
+    sind kurze JavaScript-Ausdrücke in der Konfiguration.
+-->
+<!--frFR:
+    Un petit proxy inverse configuré par un seul fichier JSON. Chaque requête
+    entrante est transmise à l'un des backends configurés ("forwarders").
+    Auparavant, le proxy peut interroger des services tiers ("state APIs"),
+    par exemple un filtre anti-bots comme reCAPTCHA ou friendlycaptcha ou un
+    service d'authentification, et répondre lui-même à la requête selon
+    leurs réponses. Les en-têtes de requête et de réponse peuvent être
+    réécrits au passage. Toutes les décisions sont de courtes expressions
+    JavaScript dans la configuration.
+-->
 
 <div class="wd-table-of-contents">
     <h2 id="content">Content<!--deDE:Inhalt--><!--frFR:Contenu--></h2>
@@ -50,416 +74,582 @@ forwarded requests.
 Installation
 ------------
 
-You can install via package manager, simply download the compiled version as
-zip file here and inject or request via CDN in HTML:
+Install the command globally via npm and start it in the folder which holds
+your "configuration.json":
 <!--deDE:
-    Sie können das Paket über den Paketmanager installieren oder einfach die
-    kompilierte Version als ZIP-Datei hier herunterladen und in HTML einbinden
-    oder über ein CDN abrufen:
+    Installieren Sie den Befehl global über npm und starten Sie ihn in dem
+    Ordner, der Ihre "configuration.json" enthält:
 -->
 <!--frFR:
-    Vous pouvez installer le paquet via le gestionnaire de paquets ou
-    simplement télécharger ici la version compilée sous forme de fichier ZIP,
-    puis l'intégrer dans une page HTML ou la récupérer via un CDN:
+    Installez la commande globalement via npm et lancez-la dans le dossier
+    qui contient votre "configuration.json":
 -->
 
 ```bash
-npm install reverse-proxy-middleware
+npm install --global reverse-proxy-middleware
+reverse-proxy-middleware
 ```
 
-<!--|deDE:Beispiel-->
-<!--|frFR:Exemple-->
-Example
--------
-
-### Simple forwarding
-
-Simple reverse proxy request from `http://localhost:8080` to
-`https://www.google.com` without modifying the entire request.
+Or run the container image and mount the configuration into it:
+<!--deDE:
+    Oder starten Sie das Container-Image und binden Sie die Konfiguration
+    ein:
+-->
+<!--frFR:Ou lancez l'image de conteneur et montez-y la configuration:-->
 
-```
-{
-  "forwarders": {
-    "google": {
-      "host": "www.google.com"
-    }
-  }
-}
+```bash
+docker run \
+    --name reverse-proxy-middleware \
+    --publish 8080:8080 \
+    --rm \
+    --volume "$(pwd)/configuration.json:/application/configuration.json" \
+    ghcr.io/thaibault/reverse-proxy-middleware:latest
 ```
 
-Since the proxy starts at localhost on port 8080 as a default configuration you
-can check the configuration via a simple curl command:
+"systemd.service" in this repository is a unit which runs the container in
+the Docker network "proxy" (e.g. behind the
+[proxy](https://tsickert.com/proxy) project) and reads its configuration from
+"/srv/http/reverse-proxy-middleware/configuration.json".
+<!--deDE:
+    "systemd.service" in diesem Repository ist eine Unit, die den Container
+    im Docker-Netzwerk "proxy" betreibt (z. B. hinter dem Projekt
+    [proxy](https://tsickert.com/proxy)) und ihre Konfiguration aus
+    "/srv/http/reverse-proxy-middleware/configuration.json" liest.
+-->
+<!--frFR:
+    "systemd.service" dans ce dépôt est une unité qui exécute le conteneur
+    dans le réseau Docker "proxy" (par exemple derrière le projet
+    [proxy](https://tsickert.com/proxy)) et lit sa configuration depuis
+    "/srv/http/reverse-proxy-middleware/configuration.json".
+-->
 
-```curl --verbose http://localhost:8080```
+Configuration
+-------------
 
-Behind there are a some commonly use defaults configured under key
-"configuration" in [package.json](package.json). Please have a look.
+On start, the defaults under the key "configuration" in
+[package.json](package.json) are extended by "configuration.json" and then by
+"secure-configuration.json" from the current working directory. Both files
+are optional, the second one is meant for secrets. The top level options are:
+<!--deDE:
+    Beim Start werden die Standardwerte unter dem Schlüssel "configuration"
+    in [package.json](package.json) durch "configuration.json" und danach
+    durch "secure-configuration.json" aus dem aktuellen Arbeitsverzeichnis
+    erweitert. Beide Dateien sind optional, die zweite ist für Geheimnisse
+    gedacht. Die Optionen der obersten Ebene sind:
+-->
+<!--frFR:
+    Au démarrage, les valeurs par défaut sous la clé "configuration" dans
+    [package.json](package.json) sont étendues par "configuration.json" puis
+    par "secure-configuration.json" du répertoire de travail courant. Les
+    deux fichiers sont facultatifs, le second est destiné aux secrets. Les
+    options de premier niveau sont:
+-->
 
-### Distributing requests to different backends
+- "port" (default: the environment variable "PORT" or "8080"): where the proxy listens.<!--deDE:"port" (Standard: die Umgebungsvariable "PORT" oder "8080"): wo der Proxy lauscht.--><!--frFR:"port" (par défaut: la variable d'environnement "PORT" ou "8080"): où le proxy écoute.-->
+- "host" (default empty, meaning all network interfaces): the address to listen on, e.g. "127.0.0.1".<!--deDE:"host" (Standard leer, also alle Netzwerkschnittstellen): die Adresse, auf der gelauscht wird, z. B. "127.0.0.1".--><!--frFR:"host" (vide par défaut, donc toutes les interfaces réseau): l'adresse d'écoute, par exemple "127.0.0.1".-->
+- "forwarders": the backends, see below.<!--deDE:"forwarders": die Backends, siehe unten.--><!--frFR:"forwarders": les backends, voir ci-dessous.-->
+- "parseBody" (default "false"): parses JSON request bodies for expressions.<!--deDE:"parseBody" (Standard "false"): wertet JSON-Anfragekörper für Ausdrücke aus.--><!--frFR:"parseBody" (par défaut "false"): analyse les corps de requête JSON pour les expressions.-->
+- "logLevel" (default "info"): one of "debug", "info", "warn", "error" and "critical". "debug" logs every forwarded header.<!--deDE:"logLevel" (Standard "info"): einer von "debug", "info", "warn", "error" und "critical". "debug" protokolliert jeden weitergeleiteten Header.--><!--frFR:"logLevel" (par défaut "info"): l'un de "debug", "info", "warn", "error" et "critical". "debug" journalise chaque en-tête transmis.-->
+- "publicKeyPath" and "privateKeyPath": certificate and key files which switch the proxy to HTTPS, see below.<!--deDE:"publicKeyPath" und "privateKeyPath": Zertifikats- und Schlüsseldatei, die den Proxy auf HTTPS umstellen, siehe unten.--><!--frFR:"publicKeyPath" et "privateKeyPath": fichiers de certificat et de clé qui font passer le proxy en HTTPS, voir ci-dessous.-->
+- "nodeServerOptions": further options of the HTTPS server, see [Node.js](https://nodejs.org/api/https.html#httpscreateserveroptions-requestlistener).<!--deDE:"nodeServerOptions": weitere Optionen des HTTPS-Servers, siehe [Node.js](https://nodejs.org/api/https.html#httpscreateserveroptions-requestlistener).--><!--frFR:"nodeServerOptions": autres options du serveur HTTPS, voir [Node.js](https://nodejs.org/api/https.html#httpscreateserveroptions-requestlistener).-->
 
-Here is how to distribute incoming requests randomly between google and bing:
+### HTTPS
 
-```
+With "publicKeyPath" and "privateKeyPath" set, the proxy only accepts HTTPS
+connections. Relative paths start at the working directory, the files are
+read on start:
+<!--deDE:
+    Sind "publicKeyPath" und "privateKeyPath" gesetzt, akzeptiert der Proxy
+    nur HTTPS-Verbindungen. Relative Pfade beginnen im Arbeitsverzeichnis,
+    die Dateien werden beim Start gelesen:
+-->
+<!--frFR:
+    Lorsque "publicKeyPath" et "privateKeyPath" sont définis, le proxy
+    n'accepte que des connexions HTTPS. Les chemins relatifs partent du
+    répertoire de travail, les fichiers sont lus au démarrage:
+-->
+
+```JSON
 {
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
-      "useExpression": "Math.random() < 0.5"
-    },
-
-    "google": {
-      "host": "www.google.com"
-    }
-  }
+    "publicKeyPath": "certificate.pem",
+    "privateKeyPath": "key.pem"
 }
 ```
 
-Forwarders are iterated in alphabetical order of their name and `useExpression`
-are getting evaluated. Since "google" is always "used" it depends on the random
-outcome of bing's expression if it is beeing used or not.
-
-Since this proxy just streams the whole request through it could be used as
-basic load balancer with this configuration.
+Encrypted connections always use HTTP/1.1. Certificate and key end up in
+"nodeServerOptions" as "cert" and "key" unless these are given there already.
+<!--deDE:
+    Verschlüsselte Verbindungen nutzen immer HTTP/1.1. Zertifikat und
+    Schlüssel landen als "cert" und "key" in "nodeServerOptions", sofern
+    diese dort nicht schon angegeben sind.
+-->
+<!--frFR:
+    Les connexions chiffrées utilisent toujours HTTP/1.1. Le certificat et
+    la clé sont placés dans "nodeServerOptions" sous "cert" et "key", sauf
+    s'ils y sont déjà indiqués.
+-->
 
-### Rewriting headers for underlying backend
+<!--|deDE:Weiterleitung-->
+<!--|frFR:Redirection-->
+### Simple forwarding
 
-Headers can be replaced in both directions. Client-Request to forward or
-retrieved responses given from configured backend:
+This configuration passes every request on "http://localhost:8080" to
+"https://example.com" unchanged:
+<!--deDE:
+    Diese Konfiguration reicht jede Anfrage an "http://localhost:8080"
+    unverändert an "https://example.com" weiter:
+-->
+<!--frFR:
+    Cette configuration transmet telle quelle chaque requête sur
+    "http://localhost:8080" à "https://example.com":
+-->
 
-```
+```JSON
 {
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
-
-      "headerTransformations": {
-        "send": {
-          "source": "/X-Special-Client-Header-Name: (.+)/gi",
-          "target": "'New-Header-Name: $1'"
-        },
-
-        "retrieve": {
-          "source": "/set-cookie: (.+)/gi",
-          "target": "'X-Prevented-Cookie: $1'"
+    "forwarders": {
+        "example": {
+            "host": "example.com"
         }
-      }
     }
-  }
 }
 ```
 
-Test via:
-
-```
-  curl \
-    --header 'X-Special-Client-Header-Name: value' \
-    --verbose \
-    http://localhost:8080 \
-      1>/dev/null
+```bash
+curl --verbose http://localhost:8080
 ```
 
-You should see a lot of cookie header ("set-cookie: ..." replaced by
-"X-Prevented-Cookie: ...".
-Note that muting the standart output ("1>/dev/null") enables you to focus on
-retrieved headers printed via secondary error output.
+A forwarder has the following options, the defaults come from the special
+forwarder "base":
+<!--deDE:
+    Ein Forwarder hat die folgenden Optionen, die Standardwerte stammen vom
+    besonderen Forwarder "base":
+-->
+<!--frFR:
+    Un forwarder possède les options suivantes, les valeurs par défaut
+    viennent du forwarder spécial "base":
+-->
 
-### State-APIs
+- "host" (default "localhost"), "port" (default "443") and "tls" (default "true"): the backend.<!--deDE:"host" (Standard "localhost"), "port" (Standard "443") und "tls" (Standard "true"): das Backend.--><!--frFR:"host" (par défaut "localhost"), "port" (par défaut "443") et "tls" (par défaut "true"): le backend.-->
+- "rejectUnauthorized" (default "false"): set it to "true" to only accept backends with a valid certificate.<!--deDE:"rejectUnauthorized" (Standard "false"): auf "true" setzen, um nur Backends mit gültigem Zertifikat zu akzeptieren.--><!--frFR:"rejectUnauthorized" (par défaut "false"): le mettre à "true" pour n'accepter que les backends ayant un certificat valide.-->
+- "useExpression" (default "true"): decides whether this forwarder takes the request.<!--deDE:"useExpression" (Standard "true"): entscheidet, ob dieser Forwarder die Anfrage übernimmt.--><!--frFR:"useExpression" (par défaut "true"): décide si ce forwarder prend la requête.-->
+- "headerTransformations": rewrites headers, see below.<!--deDE:"headerTransformations": schreibt Header um, siehe unten.--><!--frFR:"headerTransformations": réécrit les en-têtes, voir ci-dessous.-->
+- "stateAPIs": requests to third party services, see below.<!--deDE:"stateAPIs": Anfragen an Dienste von Drittanbietern, siehe unten.--><!--frFR:"stateAPIs": requêtes vers des services tiers, voir ci-dessous.-->
 
-State-APIs enables you to conditionally trigger requests to third party
-endpoints and use responses for further decisions how to proceed.
-When a state api is used for a specified request that response can be used via
-expressions to transform subsequent api requests, decide which backend to use
-or transform the final backend request.
+For a plain HTTP backend set "tls" to "false" and "port" to e.g. "80".
+<!--deDE:
+    Für ein reines HTTP-Backend setzen Sie "tls" auf "false" und "port" z.
+    B. auf "80".
+-->
+<!--frFR:
+    Pour un backend HTTP simple, mettez "tls" à "false" et "port" par
+    exemple à "80".
+-->
 
-In the following example you can see how a state api is configured to catch
-specific request to deal with. The last running pre expressions which results
-in a boolean value will trigger if the referenced state api should be used for
-given request.
+<!--|deDE:Anfragen auf mehrere Backends verteilen-->
+<!--|frFR:Répartir les requêtes sur plusieurs backends-->
+### Distributing requests
 
-Here is an example:
+Forwarders are tried in alphabetical order of their names. The first one whose
+"useExpression" results in "true" gets the request. This distributes requests
+randomly between two backends, like a basic load balancer:
+<!--deDE:
+    Forwarder werden in alphabetischer Reihenfolge ihrer Namen geprüft. Der
+    erste, dessen "useExpression" "true" ergibt, erhält die Anfrage. So
+    werden Anfragen zufällig auf zwei Backends verteilt, wie bei einem
+    einfachen Load-Balancer:
+-->
+<!--frFR:
+    Les forwarders sont essayés dans l'ordre alphabétique de leurs noms. Le
+    premier dont "useExpression" donne "true" reçoit la requête. Ainsi, les
+    requêtes sont réparties aléatoirement entre deux backends, comme avec un
+    simple répartiteur de charge:
+-->
 
-```
+```JSON
 {
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
-
-      "stateAPIs": {
-        "name": "sense",
-        "url": "https://www.google.com/search?q=${data.question}",
-
-        "data": {
-          "question": "What is the meaning of life?"
+    "forwarders": {
+        "first": {
+            "host": "first.example.com",
+            "useExpression": "Math.random() < 0.5"
         },
-
-        "expressions": {
-          "pre": "request.headers['ask-for-sense-of-live'] ? true : null",
-          "post": "response.statusCode >= 200 && response.statusCode < 300 ? null : response.statusCode"
+        "second": {
+            "host": "second.example.com"
         }
-      }
     }
-  }
 }
 ```
 
-What is going on here?
-We generally forward requests to "www.bing.com" but if there is a header called
-"ask-for-sense-of-live" present in client request we will first ask google for
-the meaning of life. If google answers with a "negative" response code not
-between 200 and 300 we will just do the final forwarding to bing. If google
-responses in a positive manner the resulting status code we will be used for
-answering client and no forwarding to "www.bing.com" happens.
-
-Here es a test curl command:
-
-```
-  curl \
-    --header 'ask-for-sense-of-live: value' \
-    --verbose \
-    http://localhost:8080 \
-      1>/dev/null
-```
-
-This should result in a simple response but:
-
-```curl --verbose http://localhost:8080 1>/dev/null```
-
-will finally request "www.bing.com".
-
-Pre and post evaluations can have various results. The meanings of them are
-described here:
-
-### Pre-Evaluation Results
-
-| Result            | Meaning                                                                                                                                                                |
-|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| break (string)    | Do not evaluate subsequent pre evaluations.                                                                                                                            |
-| null or undefined | Just jump to the next evaluation to run.                                                                                                                               |
-| true (boolean)    | Use this state api configuration. Run the configured request.                                                                                                          |
-| false (boolean)   | Do not use this state api and to not run subsequent pre evaluations.                                                                                                   |
-| code (number)     | Answer client request with provided http status code and do not run any subsequent pre-evaluations, state-api request or request forwarding to the underlying backend. |
-
-### Post-Evaluation Results
-
-| Result            | Meaning                                                                                                                                                                 |
-|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| break (string)    | Do not evaluate subsequent post evaluations.                                                                                                                            |
-| null or undefined | Just jump to the next evaluation to run.                                                                                                                                |
-| code (number)     | Answer client request with provided http status code and do not run any subsequent post-evaluations, state-api request or request forwarding to the underlying backend. |
+Expressions can also route by path, e.g.
+"request.url.startsWith('/api/')". If no forwarder matches, the client gets
+status code "502".
+<!--deDE:
+    Ausdrücke können auch nach Pfad weiterleiten, z. B.
+    "request.url.startsWith('/api/')". Passt kein Forwarder, erhält der Client
+    den Statuscode "502".
+-->
+<!--frFR:
+    Les expressions peuvent aussi aiguiller selon le chemin, par exemple
+    "request.url.startsWith('/api/')". Si aucun forwarder ne correspond, le
+    client reçoit le code de statut "502".
+-->
 
-### Smart configurations
+<!--|deDE:Header umschreiben-->
+<!--|frFR:Réécrire les en-têtes-->
+### Rewriting headers
 
-Whenever you can configure list of items you can either use just one or a list
-of them. Consider this configuration example:
+"send" transformations apply to the request header sent to the backend,
+"retrieve" transformations to the response header sent back to the client.
+"source" is an expression resulting in a regular expression or string to
+search for, "target" one resulting in its replacement:
+<!--deDE:
+    "send"-Transformationen gelten für den Anfrage-Header, der an das Backend
+    geht, "retrieve"-Transformationen für den Antwort-Header, der zum Client
+    zurückgeht. "source" ist ein Ausdruck, der einen regulären Ausdruck oder
+    eine zu suchende Zeichenkette ergibt, "target" einer, der deren Ersatz
+    ergibt:
+-->
+<!--frFR:
+    Les transformations "send" s'appliquent à l'en-tête de requête envoyé au
+    backend, les transformations "retrieve" à l'en-tête de réponse renvoyé au
+    client. "source" est une expression donnant une expression régulière ou
+    une chaîne à rechercher, "target" une expression donnant son
+    remplacement:
+-->
 
-```
+```JSON
 {
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
-
-      "headerTransformations": [{...}, {...}, ...],
-
-      "stateAPIs": {
-        "expressions": {
-          "pre": ["...", "...", ...],
-          "post": ["...", "...", ...]
+    "forwarders": {
+        "example": {
+            "host": "example.com",
+            "headerTransformations": {
+                "send": {
+                    "source": "/X-Special-Client-Header-Name: (.+)/gi",
+                    "target": "'New-Header-Name: $1'"
+                },
+                "retrieve": {
+                    "source": "/set-cookie: (.+)/gi",
+                    "target": "'X-Prevented-Cookie: $1'"
+                }
+            }
         }
-      }
     }
-  }
 }
 ```
 
-If only one item is needed please consider that:
-
+```bash
+curl \
+    --header 'X-Special-Client-Header-Name: value' \
+    --output /dev/null \
+    --verbose \
+    http://localhost:8080
 ```
-{
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
 
-      "headerTransformations": [{...}],
+The backend gets "New-Header-Name: value" and every "set-cookie" header of the
+response arrives as "X-Prevented-Cookie". A transformation without "source"
+adds the header given by "target", e.g.
+"{\"target\": \"'X-Forwarded-By: proxy'\"}". The "host" header is always
+replaced by the backend's host.
+<!--deDE:
+    Das Backend erhält "New-Header-Name: value" und jeder
+    "set-cookie"-Header der Antwort kommt als "X-Prevented-Cookie" an. Eine
+    Transformation ohne "source" fügt den in "target" angegebenen Header
+    hinzu, z. B. "{\"target\": \"'X-Forwarded-By: proxy'\"}". Der
+    "host"-Header wird immer durch den Host des Backends ersetzt.
+-->
+<!--frFR:
+    Le backend reçoit "New-Header-Name: value" et chaque en-tête
+    "set-cookie" de la réponse arrive sous la forme "X-Prevented-Cookie".
+    Une transformation sans "source" ajoute l'en-tête donné par "target",
+    par exemple "{\"target\": \"'X-Forwarded-By: proxy'\"}". L'en-tête
+    "host" est toujours remplacé par l'hôte du backend.
+-->
+
+### State APIs
 
-      "stateAPIs": {
-        "expressions": {
-          "pre": ["..."],
-          "post": ["..."]
+A state API is a request to a third party service which runs before the
+request is forwarded. Its "pre" expressions decide whether it runs, its
+"post" expressions evaluate its response. This forwarder only passes requests
+on if an authentication service accepts their token:
+<!--deDE:
+    Eine State-API ist eine Anfrage an einen Dienst eines Drittanbieters,
+    die vor dem Weiterleiten der Anfrage läuft. Ihre "pre"-Ausdrücke
+    entscheiden, ob sie läuft, ihre "post"-Ausdrücke werten ihre Antwort
+    aus. Dieser Forwarder reicht Anfragen nur weiter, wenn ein
+    Authentifizierungsdienst ihr Token akzeptiert:
+-->
+<!--frFR:
+    Une state API est une requête vers un service tiers qui s'exécute avant
+    la transmission de la requête. Ses expressions "pre" décident si elle
+    s'exécute, ses expressions "post" évaluent sa réponse. Ce forwarder ne
+    transmet les requêtes que si un service d'authentification accepte leur
+    jeton:
+-->
+
+```JSON
+{
+    "forwarders": {
+        "example": {
+            "host": "example.com",
+            "stateAPIs": {
+                "name": "authentication",
+                "urlExpression": "`https://auth.example.com/check?token=${encodeURIComponent(request.headers['x-token'])}`",
+                "options": {"headers": {"accept": "application/json"}},
+                "expressions": {
+                    "pre": "request.headers['x-token'] ? true : 401",
+                    "post": "stateAPI.response?.ok ? null : 403"
+                }
+            }
         }
-      }
     }
-  }
 }
 ```
 
-is equivalent to:
+Requests without an "X-Token" header are answered with "401", requests whose
+token the service rejects with "403", all others reach "example.com". The
+service is requested via
+[fetch](https://developer.mozilla.org/docs/Web/API/fetch) with the given
+"options". "url" sets a fixed address instead of
+"urlExpression".
+<!--deDE:
+    Anfragen ohne "X-Token"-Header werden mit "401" beantwortet, Anfragen,
+    deren Token der Dienst ablehnt, mit "403", alle anderen erreichen
+    "example.com". Der Dienst wird über
+    [fetch](https://developer.mozilla.org/docs/Web/API/fetch) mit den
+    angegebenen "options" angefragt. "url" setzt statt "urlExpression" eine
+    feste Adresse.
+-->
+<!--frFR:
+    Les requêtes sans en-tête "X-Token" reçoivent "401", celles dont le
+    service rejette le jeton "403", toutes les autres atteignent
+    "example.com". Le service est interrogé via
+    [fetch](https://developer.mozilla.org/docs/Web/API/fetch) avec les
+    "options" données. "url" définit une adresse fixe à la place de
+    "urlExpression".
+-->
 
-```
-{
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
+"pre" and "post" accept a single expression or a list, which runs in order.
+The result of each "pre" expression means:
+<!--deDE:
+    "pre" und "post" akzeptieren einen einzelnen Ausdruck oder eine Liste,
+    die der Reihe nach läuft. Das Ergebnis jedes "pre"-Ausdrucks bedeutet:
+-->
+<!--frFR:
+    "pre" et "post" acceptent une seule expression ou une liste, exécutée
+    dans l'ordre. Le résultat de chaque expression "pre" signifie:
+-->
 
-      "headerTransformations": {...},
+- "true": run the request of this state API.<!--deDE:"true": die Anfrage dieser State-API ausführen.--><!--frFR:"true": exécuter la requête de cette state API.-->
+- "false": skip this state API and its remaining "pre" expressions.<!--deDE:"false": diese State-API und ihre übrigen "pre"-Ausdrücke überspringen.--><!--frFR:"false": ignorer cette state API et ses expressions "pre" restantes.-->
+- "'break'": stop evaluating "pre" expressions.<!--deDE:"'break'": keine weiteren "pre"-Ausdrücke auswerten.--><!--frFR:"'break'": arrêter d'évaluer les expressions "pre".-->
+- "null" or "undefined": continue with the next expression.<!--deDE:"null" oder "undefined": mit dem nächsten Ausdruck fortfahren.--><!--frFR:"null" ou "undefined": continuer avec l'expression suivante.-->
+- a number: answer the client with this status code and stop.<!--deDE:eine Zahl: dem Client mit diesem Statuscode antworten und abbrechen.--><!--frFR:un nombre: répondre au client avec ce code de statut et s'arrêter.-->
 
-      "stateAPIs": {
-        "expressions": {
-          "pre": "...",
-          "post": "..."
-        }
-      }
-    }
-  }
-}
-```
+"post" expressions know the same results except "true" and "false". If no
+expression answers the client, the next state API runs and finally the
+request is forwarded.
+<!--deDE:
+    "post"-Ausdrücke kennen dieselben Ergebnisse außer "true" und "false".
+    Beantwortet kein Ausdruck den Client, läuft die nächste State-API und
+    schließlich wird die Anfrage weitergeleitet.
+-->
+<!--frFR:
+    Les expressions "post" connaissent les mêmes résultats sauf "true" et
+    "false". Si aucune expression ne répond au client, la state API suivante
+    s'exécute et la requête est finalement transmise.
+-->
 
-### Use environment variables
+<!--|deDE:Basis-Konfigurationen-->
+<!--|frFR:Configurations de base-->
+### Base configurations
 
-While some configuration values are interpret as expression to be evalued at
-runtime e.g. to decide which endpoint to use:
+Every forwarder inherits from the forwarder "base", and every state API of a
+forwarder inherits from its state API named "base". This configuration
+forwards to two backends under a sub path and asks one service with
+different data depending on the request:
+<!--deDE:
+    Jeder Forwarder erbt vom Forwarder "base" und jede State-API eines
+    Forwarders von dessen State-API namens "base". Diese Konfiguration
+    leitet an zwei Backends unter einem Unterpfad weiter und befragt einen
+    Dienst je nach Anfrage mit unterschiedlichen Daten:
+-->
+<!--frFR:
+    Chaque forwarder hérite du forwarder "base", et chaque state API d'un
+    forwarder hérite de sa state API nommée "base". Cette configuration
+    transmet vers deux backends sous un sous-chemin et interroge un service
+    avec des données différentes selon la requête:
+-->
 
-```
+```JSON
 {
-  "forwarders": {
-    "endpoint": {
-      ...
-      "useExpression": "..."
+    "forwarders": {
+        "base": {
+            "headerTransformations": {
+                "send": {
+                    "source": "/^(GET|POST) \\/(.*) (HTTP.*)$/m",
+                    "target": "'$1 /sub/path/$2 $3'"
+                }
+            }
+        },
+        "first": {
+            "host": "first.example.com",
+            "useExpression": "Math.random() < 0.5"
+        },
+        "second": {
+            "host": "second.example.com",
+            "stateAPIs": [
+                {
+                    "name": "base",
+                    "urlExpression": "`https://service.example.com/?q=${data.query}`",
+                    "expressions": {
+                        "pre": "request.headers[data.header] ? true : null",
+                        "post": "stateAPI.response?.data?.allowed ? null : 403"
+                    }
+                },
+                {
+                    "name": "cats",
+                    "data": {"header": "x-cats", "query": "cats"}
+                },
+                {
+                    "name": "dogs",
+                    "data": {"header": "x-dogs", "query": "dogs"}
+                }
+            ]
+        }
     }
-  }
 }
 ```
 
-Every item can utilize expression to dynamically derive intial configurations:
+"data" holds any values for the expressions. JSON responses of state APIs are
+available as "stateAPI.response.data".
+<!--deDE:
+    "data" enthält beliebige Werte für die Ausdrücke. JSON-Antworten von
+    State-APIs stehen als "stateAPI.response.data" zur Verfügung.
+-->
+<!--frFR:
+    "data" contient des valeurs quelconques pour les expressions. Les
+    réponses JSON des state APIs sont disponibles sous
+    "stateAPI.response.data".
+-->
 
-```
-{
-  "port": {
-    "__evaluate__": "environment.PORT ?? 8080"
-  },
-  ...
-}
-```
+<!--|deDE:Ausdrücke-->
+<!--|frFR:Expressions-->
+### Expressions
 
-If an environment variabel "PORT" is set it will be used or "8080" as a
-fallback.
+Every expression is a JavaScript expression with access to:
+<!--deDE:Jeder Ausdruck ist ein JavaScript-Ausdruck mit Zugriff auf:-->
+<!--frFR:Chaque expression est une expression JavaScript ayant accès à:-->
 
-### Use Base Forwarder
+- "request": the client request with "url", "method" and "headers".<!--deDE:"request": die Client-Anfrage mit "url", "method" und "headers".--><!--frFR:"request": la requête du client avec "url", "method" et "headers".-->
+- "response": the response to the client (not the one of a state API).<!--deDE:"response": die Antwort an den Client (nicht die einer State-API).--><!--frFR:"response": la réponse au client (pas celle d'une state API).-->
+- "stateAPI": the current state API with its "configuration", "error" and "response".<!--deDE:"stateAPI": die aktuelle State-API mit "configuration", "error" und "response".--><!--frFR:"stateAPI": la state API courante avec "configuration", "error" et "response".-->
+- "stateAPIs": all state APIs of the forwarder by name, e.g. in header transformations.<!--deDE:"stateAPIs": alle State-APIs des Forwarders nach Namen, z. B. in Header-Transformationen.--><!--frFR:"stateAPIs": toutes les state APIs du forwarder par nom, par exemple dans les transformations d'en-têtes.-->
+- "data": the state API's "data", the forwarder in "useExpression" and both sockets in header transformations.<!--deDE:"data": die "data" der State-API, der Forwarder in "useExpression" und beide Sockets in Header-Transformationen.--><!--frFR:"data": les "data" de la state API, le forwarder dans "useExpression" et les deux sockets dans les transformations d'en-têtes.-->
+- "error": the error of a failed state API request.<!--deDE:"error": der Fehler einer fehlgeschlagenen State-API-Anfrage.--><!--frFR:"error": l'erreur d'une requête de state API échouée.-->
+- "array", "datetime", "object", "string", "utility" and more: helpers of [clientnode](https://tsickert.com/clientnode).<!--deDE:"array", "datetime", "object", "string", "utility" und mehr: Hilfsfunktionen von [clientnode](https://tsickert.com/clientnode).--><!--frFR:"array", "datetime", "object", "string", "utility" et d'autres: fonctions utilitaires de [clientnode](https://tsickert.com/clientnode).-->
 
-Base forwarder are inherited by every specific forwarder. This configuration:
+For example, this send transformation passes the answer of the
+authentication service from above on to the backend:
+<!--deDE:
+    Diese Send-Transformation gibt zum Beispiel die Antwort des
+    Authentifizierungsdienstes von oben an das Backend weiter:
+-->
+<!--frFR:
+    Par exemple, cette transformation "send" transmet au backend la réponse
+    du service d'authentification ci-dessus:
+-->
 
-```
+```JSON
 {
-  "forwarders": {
-    "base: {
-      "headerTransformations": {
-        "send": {
-          "source": "/(GET|POST) \\/.* (.*)/",
-          "target": "'$1 /sub/path/to/forward/to $2'"
-        }
-      }
-    },
-
-    "bing": {
-      "host": "www.bing.com",
-      "useExpression": "Math.random() < 0.5"
-    },
-
-    "google": {
-      "host": "www.google.com"
-    }
-  }
+    "target": "`X-Allowed: ${stateAPIs.authentication.response?.data?.allowed}`"
 }
 ```
 
-is equivalent to:
+<!--|deDE:Einzelwerte oder Listen-->
+<!--|frFR:Valeurs uniques ou listes-->
+### Single values or lists
 
-```
-{
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
-
-      "useExpression": "Math.random() < 0.5",
+"headerTransformations.send", "headerTransformations.retrieve", "stateAPIs",
+"expressions.pre" and "expressions.post" take a single item or a list of
+items. "{...}" means the same as "[{...}]".
+<!--deDE:
+    "headerTransformations.send", "headerTransformations.retrieve",
+    "stateAPIs", "expressions.pre" und "expressions.post" nehmen ein
+    einzelnes Element oder eine Liste von Elementen. "{...}" bedeutet
+    dasselbe wie "[{...}]".
+-->
+<!--frFR:
+    "headerTransformations.send", "headerTransformations.retrieve",
+    "stateAPIs", "expressions.pre" et "expressions.post" acceptent un seul
+    élément ou une liste d'éléments. "{...}" signifie la même chose que
+    "[{...}]".
+-->
 
-      "headerTransformations": {
-        "send": {
-          "source": "/(GET|POST) \\/.* (.*)/",
-          "target": "'$1 /sub/path/to/forward/to $2'"
-        }
-      }
-    },
+<!--|deDE:Umgebungsvariablen-->
+<!--|frFR:Variables d'environnement-->
+### Environment variables
 
-    "google": {
-      "host": "www.google.com",
+Any value of the configuration can be computed once on start with
+"__evaluate__", which has access to "environment" and "configuration":
+<!--deDE:
+    Jeder Wert der Konfiguration lässt sich beim Start einmalig über
+    "__evaluate__" berechnen, das Zugriff auf "environment" und
+    "configuration" hat:
+-->
+<!--frFR:
+    Toute valeur de la configuration peut être calculée une fois au
+    démarrage via "__evaluate__", qui a accès à "environment" et
+    "configuration":
+-->
 
-      "headerTransformations": {
-        "send": {
-          "source": "/(GET|POST) \\/.* (.*)/",
-          "target": "'$1 /sub/path/to/forward/to $2'"
+```JSON
+{
+    "forwarders": {
+        "example": {
+            "host": {
+                "__evaluate__": "environment.BACKEND_HOST ?? 'example.com'"
+            }
         }
-      }
     }
-  }
 }
 ```
 
-### Use base State-APIs
-
-As we support generic base forwarder confgurations there are also base state
-api configuraton sections. Consider the follwing configuration example:
-
-```
-{
-  "forwarders": {
-    "bing": {
-      "host": "www.bing.com",
-
-      "stateAPIs": [
-        {
-          "name": "base",
-          "url": "https://www.google.com/search?q=${data.query}",
-
-          "expressions": {
-            "pre": "request.headers['ask-google'] ? true : null",
-            "post": "response.statusCode >= 200 && response.statusCode < 300 ? null : response.statusCode"
-          }
-        }
-
-        {
-          "name": "sense",
-
-          "data": {
-            "query": "What is the meaning of life?"
-          }
-        },
+The proxy then forwards to the host given in the environment variable
+"BACKEND_HOST" or to "example.com". The default "port" works the same way
+with "PORT".
+<!--deDE:
+    Der Proxy leitet dann an den in der Umgebungsvariable "BACKEND_HOST"
+    angegebenen Host weiter oder an "example.com". Der Standardwert von
+    "port" funktioniert genauso mit "PORT".
+-->
+<!--frFR:
+    Le proxy transmet alors à l'hôte donné dans la variable d'environnement
+    "BACKEND_HOST" ou à "example.com". La valeur par défaut de "port"
+    fonctionne de la même façon avec "PORT".
+-->
 
-        {
-          "name": "nonesense",
+<!--|deDE:Entwicklung-->
+<!--|frFR:Développement-->
+Development
+-----------
 
-          "data": {
-            "query": "baby cats"
-          }
-        }
-      ]
-    }
-  }
-}
+```bash
+yarn install
+yarn check
+yarn test
+yarn serve:simple
 ```
 
-Note that url and expression are inherited to the state apis "sense" and
-"nonsense".
-The Data field can save various configuration items to be used in runtime
-expressions.
-Please also note that it is possible to access configuration, request or
-response informations from other state apis in every runtime expression.
-
-Every expression can access the following environment:
-
-| Name      | Meaning                                                |
-|-----------|--------------------------------------------------------|
-| data      | Generic configuration items.                           |
-| error     | Error object if some occured.                          |
-| request   | Client request informations.                           |
-| response  | Response informations (available in post evaluations). |
-| stateAPIs | Access oher state api informations.                    |
-| Tools     | [see](https://www.npmjs.com/package/clientnode)        |
+"yarn check" checks types and lints, "yarn serve:&lt;name&gt;" builds the
+proxy and starts it with one of the configurations in "examples/" ("headers",
+"random", "simple" or "state-apis").
+<!--deDE:
+    "yarn check" prüft Typen und lintet, "yarn serve:&lt;name&gt;" baut den
+    Proxy und startet ihn mit einer der Konfigurationen in "examples/"
+    ("headers", "random", "simple" oder "state-apis").
+-->
+<!--frFR:
+    "yarn check" vérifie les types et lance le linter, "yarn
+    serve:&lt;name&gt;" construit le proxy et le lance avec l'une des
+    configurations de "examples/" ("headers", "random", "simple" ou
+    "state-apis").
+-->