doc: add virtual hosting example

doc/README.md

@@ -19,6 +19,7 @@
 
 ### Utilisation
 
+- [(FR) - Le cas du "virtual hosting"](./fr/tutorials/virtual-hosting.md)
 - [(FR) - Ajouter un layer de type "file d'attente"](./fr/tutorials/add-queue-layer.md)
 - [(FR) - Ajouter une authentification OpenID Connect](./fr/tutorials/add-oidc-authn-layer.md)
 - [(FR) - Amorçage d'un serveur Bouncer via la configuration](./fr/tutorials/bootstrapping.md)

doc/fr/tutorials/virtual-hosting.md

@@ -0,0 +1,129 @@
+# Le cas du "virtual hosting"
+
+De nombreux serveurs HTTP utilisent le mécanisme du ["virtual hosting"](https://en.wikipedia.org/wiki/Virtual_hosting) afin d'héberger plusieurs sites/applications différentes sur un même serveur, se basant alors sur l'entête HTTP `Host` pour effectuer le routage.
+
+## Exemple
+
+Pour exemple, avec le site [example.net](https://example.net) il est facile de tester ce type de comportement. Ainsi, en exécutant une requête HTTP avec `curl`:
+
+```shell
+curl -I https://example.net
+```
+
+On obtient le résultat suivant:
+
+```
+HTTP/2 200
+accept-ranges: bytes
+age: 568237
+cache-control: max-age=604800
+content-type: text/html; charset=UTF-8
+date: Thu, 27 Jun 2024 08:32:46 GMT
+etag: "3147526947"
+expires: Thu, 04 Jul 2024 08:32:46 GMT
+last-modified: Thu, 17 Oct 2019 07:18:26 GMT
+server: ECAcc (bsb/2789)
+x-cache: HIT
+content-length: 1256
+```
+
+Ce résultat indique que le serveur a correctement orienté notre requête (code HTTP `200`) et qu'il nous a renvoyé la réponse attendue.
+
+Si maintenant on modifie l'entête `Host` de notre requête pour la remplacer par une valeur arbitraire:
+
+```shell
+curl -I -H 'Host: localhost:8080' https://example.net
+```
+
+On obtient alors le résultat:
+
+```
+HTTP/2 404
+content-type: text/html
+date: Thu, 27 Jun 2024 08:38:04 GMT
+server: ECAcc (bsb/2789)
+content-length: 345
+```
+
+Le serveur nous répond avec un code HTTP `404`, indiquant qu'il n'a pas trouvé la page demandée.
+
+> **Note**
+> Le code HTTP retourné par le serveur peut varier en fonction des implémentations. Parfois la requête sera orientée vers la page par défaut, parfois vous recevrez un code d'erreur HTTP comme `404`, `421`, etc.
+
+## Avec Bouncer
+
+Ce mécanisme peut parfois poser problème avec Bouncer car par défaut celui ci n'effectue pas de réécriture de l'entête `Host`. Pour exemple:
+
+1.  Créez puis activez un nouveau proxy pointant vers https://example.net
+
+    ```shell
+    bouncer admin proxy create --proxy-name example --proxy-to https://example.net
+    bouncer admin proxy update --proxy-name example --proxy-enabled=true
+    ```
+
+2.  Avec `curl`, faites une requête sur votre nouveau proxy:
+
+    ```shell
+     curl -I http://localhost:8080
+    ```
+
+    La réponse devrait ressembler à:
+
+    ```
+    HTTP/1.1 404 Not Found
+    Content-Length: 345
+    Content-Type: text/html
+    Date: Thu, 27 Jun 2024 08:49:05 GMT
+    Server: ECAcc (bsb/2789)
+    ```
+
+    On retrouve bien notre code HTTP `404` tel que vu plus haut. En effet, vu que l'on accède au proxy Bouncer avec `http://localhost:8080` alors le serveur distant recevra l'entête `Host: localhost:8080`.
+
+### Comment corriger la situation ?
+
+Le layer [`rewriter`](../references/layers/rewriter.md) a été implémenté notamment pour répondre à ce type de cas. Voyons comment l'utiliser:
+
+1. Créez puis activez un nouveau layer pour votre proxy `example`:
+
+   ```bash
+    # Création du layer
+    bouncer admin layer create --proxy-name example --layer-name host-rewrite --layer-type rewriter
+
+    # Mise à jour et activation du layer
+    bouncer admin layer update \
+        --proxy-name example \
+        --layer-name host-rewrite \
+        --layer-options '{ "rules": { "request": ["set_host(\"example.net\")"] } }' \
+        --layer-enabled=true
+   ```
+
+   > **Les règles**
+   >
+   > Le layer `rewriter` permet la modification des requêtes/réponses via un moteur de règles.
+   >
+   > [Voir la page du layer pour plus d'informations](../references/layers/rewriter.md) sur la syntaxe ainsi que sur l'API à disposition des règles.
+
+2. Testez maintenant à nouveau un appel vers votre proxy:
+
+   ```shell
+    curl -I http://localhost:8080
+   ```
+
+   La réponse devrait ressembler à:
+
+   ```
+    HTTP/1.1 200 OK
+    Accept-Ranges: bytes
+    Age: 569980
+    Cache-Control: max-age=604800
+    Content-Length: 1256
+    Content-Type: text/html; charset=UTF-8
+    Date: Thu, 27 Jun 2024 09:01:49 GMT
+    Etag: "3147526947"
+    Expires: Thu, 04 Jul 2024 09:01:49 GMT
+    Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
+    Server: ECAcc (bsb/2789)
+    X-Cache: HIT
+   ```
+
+   Cette fois ci, le serveur distant a bien identifié la cible de notre requête.