doc: add proxy http api reference

Makefile

@@ -101,6 +101,12 @@ gitea-release: tools/gitea-release/bin/gitea-release.sh goreleaser
 		GITEA_RELEASE_ATTACHMENTS="$$(find .gitea-release/* -type f)" \
 		tools/gitea-release/bin/gitea-release.sh
 
+grafterm: tools/grafterm/bin/grafterm
+	tools/grafterm/bin/grafterm -c ./misc/grafterm/dashboard.json -v job=bouncer-proxy -r 5s
+
+siege:
+	siege -i -c 100 -f ./misc/siege/urls.txt
+
 tools/gitea-release/bin/gitea-release.sh:
 	mkdir -p tools/gitea-release/bin
 	curl --output tools/gitea-release/bin/gitea-release.sh https://forge.cadoles.com/Cadoles/Jenkins/raw/branch/master/resources/com/cadoles/gitea/gitea-release.sh
@@ -110,6 +116,10 @@ tools/modd/bin/modd:
 	mkdir -p tools/modd/bin
 	GOBIN=$(PWD)/tools/modd/bin go install github.com/cortesi/modd/cmd/modd@latest
 
+tools/grafterm/bin/grafterm:
+	mkdir -p tools/grafterm/bin
+	GOBIN=$(PWD)/tools/grafterm/bin go install github.com/slok/grafterm/cmd/grafterm@v0.2.0
+
 full-version:
 	@echo $(FULL_VERSION)
 
@@ -128,4 +138,12 @@ run-redis:
 redis-shell:
 	docker exec -it \
 		bouncer-redis \
-		redis-cli
+		redis-cli
+
+run-prometheus:
+	docker kill bouncer-prometheus || exit 0
+	docker run --rm -t \
+		--name bouncer-prometheus \
+		--network host \
+		-v $(PWD)/misc/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
+		prom/prometheus

doc/README.md

@@ -10,6 +10,7 @@
 
 - [(FR) - Layers](./fr/references/layers/README.md)
 - [(FR) - Fichier de configuration](../misc/packaging/common/config.yml)
+- [(FR) - API d'administration](./fr/references/admin_api.md)
 
 ## Tutoriels
 

doc/fr/references/admin_api.md

@@ -0,0 +1,182 @@
+# API d'administration
+
+## Authentification
+
+L'ensemble des appels aux APIs HTTP du service `bouncer-admin` sont authentifiées via l'utilisation d'un jeton [JWT](https://datatracker.ietf.org/doc/html/rfc7519) signé par la clé privée du serveur.
+
+Le jeton d'accès doit être transmis avec l'ensemble des appels aux points d'entrée via l'entête HTTP `Authorization` en respectant la forme suivante:
+
+```
+Authorization: Bearer <jwt>
+```
+
+### Génération d'un jeton d'authentification
+
+La génération d'un jeton d'authentification s'effectue via la commande suivante:
+
+```shell
+bouncer auth create-token --subject "<subject>" --role "<role>"
+```
+
+Où:
+
+- `"<subject>"` est une chaîne de caractère arbitraire ayant pour objectif d'identifier de manière unique l'utilisateur associé au jeton;
+- `"<role>"` peut prendre une des deux valeurs `reader` ou `writer` correspondant aux droits suivants respectifs:
+    - droit en lecture sur l'ensemble des entités (proxy, layer);
+    - droit en lecture ET en écriture sur l'ensemble des entités.
+
+
+## Points d'entrée
+
+### `POST /api/v1/proxies`
+
+Créer un nouveau proxy
+
+#### Exemple de corps de requête
+
+```json5
+{
+  "name": "myproxy",                // OBLIGATOIRE - Nom du proxy
+  "to": "https://www.cadoles.com",  // OBLIGATOIRE - Site distant ciblé par le proxy
+  "from": ["*"]                     // OPTIONNEL - Liste de patrons de filtrage associés au proxy
+}
+```
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxy": {
+            "name": "myproxy",
+            "weight": 0,
+            "enabled": false,
+            "to": "https://www.cadoles.com",
+            "from": ["*"],
+            "createdAt": "2018-12-10T13:45:00.000Z",
+            "updatedAt": "2018-12-10T13:45:00.000Z"
+        }
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#createProxy()`](../../../internal/admin/proxy_route.go#createProxy)
+
+### `GET /api/v1/proxies/{proxyName}`
+
+Récupérer les informations complètes sur un proxy
+
+#### Paramètres
+
+- `{proxyName}` - Nom du proxy
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxy": {
+            "name": "myproxy",
+            "weight": 0,
+            "enabled": false,
+            "to": "https://www.cadoles.com",
+            "from": ["*"],
+            "createdAt": "2018-12-10T13:45:00.000Z",
+            "updatedAt": "2018-12-10T13:45:00.000Z"
+        }
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#getProxy()`](../../../internal/admin/proxy_route.go#getProxy)
+
+### `PUT /api/v1/proxies/{proxyName}`
+
+Modifier un proxy
+
+#### Exemple de corps de requête
+
+```json5
+{
+  "to": "https://www.cadoles.com",  // OPTIONNEL - Site distant ciblé par le proxy
+  "from": ["mylocalproxydomain:*"], // OPTIONNEL - Liste de patrons de filtrage associés au proxy
+  "weight": 100,                    // OPTIONNEL - Poids à associer au proxy
+  "enabled": true,                  // OPTIONNEL - Activer/désactiver le proxy
+}
+```
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxy": {
+            "name": "myproxy",
+            "weight": 100,
+            "enabled": true,
+            "to": "https://www.cadoles.com",
+            "from": ["mylocalproxydomain:*"],
+            "createdAt": "2018-12-10T13:45:00.000Z",
+            "updatedAt": "2020-10-02T15:09:00.000Z"
+        }
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#updateProxy()`](../../../internal/admin/proxy_route.go#updateProxy)
+
+### `GET /api/v1/proxies?names={name1,name2,...}`
+
+Lister les proxies existants
+
+#### Paramètres
+
+- `{names}` - Optionnel - Liste des noms de proxy à appliquer en tant que filtre
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxies": [
+            {
+                "name": "myproxy",
+                "weight": 0,
+                "enabled": false,
+            }
+        ]
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#queryProxy()`](../../../internal/admin/proxy_route.go#queryProxy)
+
+## `DELETE /api/v1/proxies/{proxyName}`
+
+Supprimer le proxy
+
+#### Paramètres
+
+- `{proxyName}` - Nom du proxy
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxyName": "myproxy"
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#deleteProxy()`](../../../internal/admin/proxy_route.go#deleteProxy)

doc/fr/tutorials/getting-started-with-sources.md

@@ -70,15 +70,15 @@ docker run --rm -t \
 
 Surveiller les sources, compiler celles ci en cas de modifications et lancer les services `bouncer-proxy` et `bouncer-admin`.
 
-#### `make test`
+### `make test`
 
 Exécuter les tests unitaires/d'intégration du projet.
 
-#### `make build`
+### `make build`
 
 Compiler une version de développement du binaire `bouncer`.
 
-#### `make docker-build`
+### `make docker-build`
 
 Construire une image Docker pour Bouncer.
 
@@ -92,6 +92,13 @@ docker run \
     bouncer server proxy run
 ```
 
+### `make grafterm`
+
+Afficher un tableau de bord [`grafterm`](https://github.com/slok/grafterm) branché sur l'instance Prometheus locale.
+
+### `make siege`
+
+Lancer une session de test [`siege`](https://github.com/JoeDog/siege) sur l'instance `bouncer-proxy` locale.
 ## Arborescence du projet
 
 ```bash

misc/grafterm/dashboard.json

@@ -0,0 +1,196 @@
+{
+  "version": "v1",
+  "datasources": {
+    "prometheus": {
+      "prometheus": {
+        "address": "http://127.0.0.1:9090"
+      }
+    }
+  },
+  "dashboard": {
+    "variables": {
+      "job": {
+        "constant": { "value": "bouncer-proxy" }
+      },
+      "interval": {
+        "interval": { "steps": 50 }
+      }
+    },
+    "widgets": [
+      {
+        "title": "Bouncer - Total queue sessions",
+        "gridPos": { "w": 20 },
+        "singlestat": {
+          "thresholds": [{ "color": "#47D038" }],
+          "query": {
+            "datasourceID": "prometheus",
+            "expr": "sum(bouncer_layer_queue_sessions{job=\"{{.job}}\"})"
+          }
+        }
+      },
+      {
+        "title": "Bouncer Traffic",
+        "gridPos": {
+          "w": 80
+        },
+        "graph": {
+          "queries": [
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(rate(bouncer_proxy_director_proxy_requests_total{job=\"{{.job}}\"}[{{.interval}}]))",
+              "legend": "req/s"
+            }
+          ]
+        }
+      },
+      {
+        "title": "Goroutines",
+        "gridPos": { "w": 20 },
+        "singlestat": {
+          "thresholds": [{ "color": "#47D038" }],
+          "query": {
+            "datasourceID": "prometheus",
+            "expr": "sum(go_goroutines{job=\"{{.job}}\"})"
+          }
+        }
+      },
+      {
+        "title": "GC duration",
+        "gridPos": { "w": 20 },
+        "singlestat": {
+          "unit": "second",
+          "query": {
+            "datasourceID": "prometheus",
+            "expr": "max(go_gc_duration_seconds{job=\"{{.job}}\"})"
+          }
+        }
+      },
+      {
+        "title": "Stack",
+        "gridPos": { "w": 20 },
+        "singlestat": {
+          "unit": "bytes",
+          "thresholds": [{ "color": "#22F1F1" }],
+          "query": {
+            "datasourceID": "prometheus",
+            "expr": "sum(go_memstats_stack_inuse_bytes{job=\"{{.job}}\"})"
+          }
+        }
+      },
+      {
+        "title": "Heap",
+        "gridPos": { "w": 20 },
+        "singlestat": {
+          "unit": "bytes",
+          "thresholds": [{ "color": "#22F1F1" }],
+          "query": {
+            "datasourceID": "prometheus",
+            "expr": "sum(go_memstats_heap_inuse_bytes{job=\"{{.job}}\"})"
+          }
+        }
+      },
+      {
+        "title": "Alloc",
+        "gridPos": { "w": 20 },
+        "singlestat": {
+          "unit": "bytes",
+          "thresholds": [{ "color": "#22F1F1" }],
+          "query": {
+            "datasourceID": "prometheus",
+            "expr": "sum(go_memstats_alloc_bytes{job=\"{{.job}}\"})"
+          }
+        }
+      },
+      {
+        "title": "Goroutines",
+        "gridPos": { "w": 50 },
+        "graph": {
+          "visualization": {
+            "legend": { "disable": true },
+            "yAxis": { "unit": "", "decimals": 2 }
+          },
+          "queries": [
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(go_goroutines{job=\"{{.job}}\"})"
+            }
+          ]
+        }
+      },
+      {
+        "title": "GC duration",
+        "gridPos": { "w": 50 },
+        "graph": {
+          "queries": [
+            {
+              "datasourceID": "prometheus",
+              "expr": "max(go_gc_duration_seconds{job=\"{{.job}}\"}) by (quantile)",
+              "legend": "Q{{.quantile}}"
+            }
+          ],
+          "visualization": {
+            "yAxis": { "unit": "second" },
+            "seriesOverride": [
+              { "regex": "^Q0$", "color": "#F9E2D2" },
+              { "regex": "^Q0.25$", "color": "#F2C96D" },
+              { "regex": "^Q0.5(0)?$", "color": "#EAB839" },
+              { "regex": "^Q0.75$", "color": "#EF843C" },
+              { "regex": "^Q1(.0)?$", "color": "#E24D42" }
+            ]
+          }
+        }
+      },
+      {
+        "title": "Memory",
+        "gridPos": { "w": 50 },
+        "graph": {
+          "visualization": {
+            "yAxis": { "unit": "byte", "decimals": 0 }
+          },
+          "queries": [
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(go_memstats_stack_inuse_bytes{job=\"{{.job}}\"})",
+              "legend": "stack inuse"
+            },
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(go_memstats_heap_inuse_bytes{job=\"{{.job}}\"})",
+              "legend": "heap inuse"
+            },
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(go_memstats_alloc_bytes{job=\"{{.job}}\"})",
+              "legend": "alloc"
+            }
+          ]
+        }
+      },
+      {
+        "title": "Memory ops rate",
+        "gridPos": {
+          "w": 50
+        },
+        "graph": {
+          "queries": [
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(rate(go_memstats_frees_total{job=\"{{.job}}\"}[{{.interval}}]))",
+              "legend": "frees/s"
+            },
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(rate(go_memstats_mallocs_total{job=\"{{.job}}\"}[{{.interval}}]))",
+              "legend": "mallocs/s"
+            },
+            {
+              "datasourceID": "prometheus",
+              "expr": "sum(rate(go_memstats_lookups_total{job=\"{{.job}}\"}[{{.interval}}]))",
+              "legend": "lookups/s"
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

misc/prometheus/prometheus.yml

@@ -0,0 +1,7 @@
+scrape_configs:
+  - job_name: bouncer-proxy
+    metrics_path: /.bouncer/metrics
+    static_configs:
+      - targets:
+          - "localhost:8080"
+    scrape_interval: 5s

misc/siege/urls.txt

@@ -0,0 +1,6 @@
+http://localhost:8080/blog/
+http://localhost:8080/services/
+http://localhost:8080/
+http://localhost:8080/recrutement/
+http://localhost:8080/faq/
+http://localhost:8080/societe/histoire/

modd.conf

@@ -14,4 +14,9 @@ layers/**
 
 {
     daemon +sigint: make run-redis
+}
+
+misc/prometheus/prometheus.yml
+{
+    daemon +sigint: make run-prometheus
 }