pingap

# Pingap

Un proxy inverse et une passerelle applicative construits sur [Cloudflare Pingora](https://github.com/cloudflare/pingora). Il se configure via des fichiers TOML ou une interface d'administration web intégrée au binaire, prend les modifications en compte sans redémarrage, et est livré avec plus de trente plugins.

[中文说明](https://github.com/vicanso/pingap/blob/main/README_zh.md) | [Documentation](https://pingap.io/) · [中文文档](https://pingap.io/zh/) | [Exemples](https://github.com/vicanso/pingap/blob/main/examples/README.md) | [Plugins](https://github.com/vicanso/pingap/blob/main/pingap-plugin/README.md) | [Crates](https://github.com/vicanso/pingap/blob/main/docs/README.md) | [Mise à niveau](https://pingap.io/guide/upgrading)

![Les requêtes provenant d'Internet passent par Pingap, qui les achemine par hôte et par chemin vers des groupes de serveurs en amont](https://raw.githubusercontent.com/vicanso/pingap/main/asset/pingap-flow.svg)

## Ce qui le distingue

- **Une interface d'administration web intégrée au binaire.** Chaque paramètre dispose d'un formulaire. Une modification est vérifiée de la même manière que `pingap -t` la vérifie avant d'être enregistrée, les versions antérieures peuvent être conservées et restaurées, et il existe des comptes en lecture seule et des jetons d'API. Sa page d'accueil affiche les graphiques du trafic des quinze dernières minutes - débit, statuts, latence, chaque amont - sans Prometheus.
- **Des modifications sans interruption de service.** Les amonts, les emplacements, les plugins et les certificats sont remplacés dans le processus en cours d'exécution (`--autoreload`). Ce qui nécessite de nouveaux écouteurs est appliqué par un redémarrage qui transfère les sockets (`--autorestart`, pour un démon sous Linux), et le processus en cours continue de servir si son remplaçant ne démarre pas.
- **Plus de trente plugins**, par emplacement et dans l'ordre où vous les listez : authentification (JWT, OIDC, clé, basic, HMAC, forward auth), règles d'accès (IP, referer, user agent, chemins bloqués), trafic (limites de débit et de bande passante, cache, mise en miroir, répartition du trafic), contenu (compression, substitution du corps, redirections, fichiers statiques, optimisation d'images) et opérations (mode maintenance, endpoint de santé, pages d'erreur). [Tous les plugins](https://github.com/vicanso/pingap/blob/main/pingap-plugin/README.md)
- **Des certificats sans tâche cron.** Let's Encrypt ou toute autre AC ACME, par HTTP-01 ou DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA et ECDSA côte à côte, OCSP stapling, et TLS mutuel envers les clients et envers les amonts.
- **Une configuration vérifiée avant d'être exécutée.** `-t` construit tout ce qu'un démarrage construirait, `--strict` refuse les clés qu'il ne connaît pas, `--diff` montre ce qu'une modification ferait. TOML, HCL ou KDL, dans des fichiers ou dans etcd, avec des secrets issus de l'environnement ou de fichiers.
- **Conçu pour être surveillé.** Métriques Prometheus (pull et push), traces OpenTelemetry, journaux d'accès en texte ou JSON avec plus de trente champs, et empreintes TLS JA4 des clients.

Le reste de ce que fait un proxy inverse est également présent : HTTP/1.1, HTTP/2, WebSocket et gRPC-web ; routage par hôte, chemin et expression régulière ; round robin, least connections, hachage cohérent et sessions persistantes, avec contrôles de santé, tentatives et disjoncteur ; backends issus du DNS (A/AAAA, SRV) ou des labels Docker ; le protocole PROXY sur les écouteurs et vers les amonts ; OpenSSL ou rustls.

Les métriques, le traçage et l'optimisation d'images sont dans les builds `-full`.

## 🚀 Démarrage

### Docker Compose

```yaml
# docker-compose.yml
services:
  pingap:
    image: vicanso/pingap:latest # for production, pin a release: vicanso/pingap:<version>-full
    container_name: pingap-instance
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      # everything Pingap keeps: configuration, certificates, cache
      - ./pingap_data:/opt/pingap
    environment:
      - PINGAP_CONF=/opt/pingap/conf
      - PINGAP_ADMIN_ADDR=0.0.0.0:80/pingap
      - PINGAP_ADMIN_USER=pingap
      - PINGAP_ADMIN_PASSWORD=<YourSecurePassword> # change this
    command:
      - pingap
      - --autoreload
```

```bash
mkdir pingap_data
docker compose up -d
```

L'interface d'administration se trouve à l'adresse http://localhost/pingap. Les images sont étiquetées `latest`, `full` et `rustls-full`, ainsi que `<version>`, `<version>-full`, `<version>-rustls-full` pour une version publiée. Chacune possède également une variante `-distroless` sans shell, où `command` doit commencer par `pingap` comme ci-dessus.

### Binaire

```bash
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | sh
```

installe la dernière version dans `/usr/local/bin/pingap` sous Linux et macOS (x86_64 et arm64). Les variables placées devant `sh` déterminent ce qui est installé :

| Variable | Effet |
| --- | --- |
| `PINGAP_FULL=1` | La build `-full`, avec toutes les fonctionnalités optionnelles |
| `PINGAP_TLS=rustls` | Linux : la build `-rustls-full`, sans OpenSSL (voir [TLS backend](#tls-backend)) |
| `PINGAP_LIBC=gnu` | Linux : la build glibc à la place de celle statique musl |
| `PINGAP_SERVICE=1` | Linux avec systemd : également le service `pingap` et une configuration de démarrage dans `/etc/pingap/conf` ; il n'est ni activé ni démarré |
| `PINGAP_VERSION=0.15.0` | Cette version à la place de la dernière |

Tous les assets sont sur la [page des releases](https://github.com/vicanso/pingap/releases).

### Une seule commande, aucun fichier de configuration

```bash
# the certificate comes from Let's Encrypt
pingap --domain=pingap.io --upstream=192.168.1.1:3000

# or bring your own
pingap --domain=pingap.io --upstream=192.168.1.1:3000 --cert=/etc/ssl/pingap.io
```

- Sans `--cert`, le certificat est commandé via HTTP-01 : le domaine doit résoudre vers cet hôte, avec le port 80 accessible. Il est conservé dans `~/.pingap/acme/<domains>.toml` et réutilisé au démarrage suivant. Ne le supprimez pas, l'émission est soumise à des limites de débit.
- `--cert` est le certificat ou le répertoire dans lequel il se trouve (`fullchain.pem` / `privkey.pem`, `cert.pem` / `key.pem` et `tls.crt` / `tls.key` sont détectés ; `--key` désigne tout autre nom). `--upstream` et `--domain` prennent des listes séparées par des virgules, `--addr` l'adresse d'écoute.
- La configuration est recréée à chaque démarrage, l'administrateur ne peut donc pas la modifier. Pour plus d'un serveur, utilisez `--conf`, avec lequel ces options ne peuvent pas être combinées.

## 📝 Configuration

```toml
[upstreams.api]
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"

[plugins.staticServe]
category = "directory"
path = "~/Downloads"

[locations.github-api]
upstream = "api"
path = "/api"
proxy_set_headers = ["Host:api.github.com"]
rewrite = "^/api/(?<path>.+)$ /$1"

[locations.static]
plugins = ["staticServe"]

[servers.test]
addr = "127.0.0.1:6118"
locations = ["github-api", "static"]
```

La même chose peut être écrite en HCL ou en KDL. Chaque clé est décrite dans la [référence de configuration](https://pingap.io/crates/config).

| | |
| --- | --- |
| `--autoreload` | Une modification est appliquée sans redémarrage : en moins de dix secondes depuis les fichiers, immédiatement depuis etcd. Ce qui nécessite un redémarrage est signalé, et attend celui-ci. Le mode pour les conteneurs |
| `-a`, `--autorestart` | Idem, plus un redémarrage qui ne perd aucune requête pour ce qu'un rechargement ne peut pas modifier, une adresse d'écoute par exemple. Pour un démon (`-d`) sous Linux ; partout ailleurs, il recharge et signale ce qui attend |
| `-t` | Construit chaque upstream, location, plugin, certificat et serveur comme le ferait un démarrage, sans rien lier |
| `--strict` | Une clé que Pingap ne connaît pas, ou une pour laquelle cette build n'a pas de fonctionnalité, est une erreur, là où elle n'est sinon qu'un avertissement. Pour `-t` en CI |
| `--diff <other>` | Affiche ce qui changerait si `<other>` remplaçait la configuration, les identifiants étant affichés sous forme de sommes de contrôle |
| `$ENV:NAME`, `$FILE:/path` | Comme valeur entière : remplacé par la variable ou le fichier au chargement de la configuration |

## 🔄 Comment une requête est traitée

![Une requête traverse le serveur, la location et ses plugins de requête jusqu'à un upstream ; la réponse revient à travers les plugins de réponse et est journalisée](https://raw.githubusercontent.com/vicanso/pingap/main/asset/pingap-steps.svg)

1. Le **serveur** accepte la connexion et choisit la **location** dont l'hôte et le chemin correspondent le mieux. Une requête qui n'en correspond à aucune reçoit une réponse `404`.
2. Les **plugins** de la location s'exécutent dans l'ordre où ils sont listés, chacun à sa propre étape : à l'aller, ou au retour. Un plugin peut répondre lui-même à la requête - un cache hit, une authentification échouée, une redirection, un fichier statique - et l'upstream n'est alors jamais sollicité.
3. Sinon, l'**upstream** de la location choisit un backend sain et la requête est transmise. Avec `max_retries`, une connexion qui ne peut pas être établie est essayée sur un autre backend ; avec `fallback_upstream`, une requête que l'upstream ne peut pas prendre est envoyée à un second upstream.
4. La réponse revient à travers les plugins de réponse jusqu'au client, et la requête est **journalisée** : journal d'accès, métriques et traces.

## 📊 Performances

Environ 147 000 requêtes par seconde pour `/ping` sur un seul thread d'un M4 Pro, avec un 99e percentile de 116µs (`wrk`, 10 connexions, sans journal d'accès).

<details>
<summary>L'exécution</summary>

```
wrk 'http://127.0.0.1:6118/ping' --latency

Running 10s test @ http://127.0.0.1:6118/ping
  2 threads and 10 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    66.41us   23.67us   1.11ms   76.54%
    Req/Sec    73.99k     2.88k   79.77k    68.81%
  Latency Distribution
     50%   67.00us
     75%   80.00us
     90%   91.00us
     99%  116.00us
  1487330 requests in 10.10s, 194.32MB read
Requests/sec: 147260.15
Transfer/sec:     19.24MB
```

</details>

## 🔧 Développement

```bash
make dev         # needs bacon: cargo install bacon
make build-web   # after a change under web/, needs Node.js
make fmt && make lint && make test
```

`make dev` compile avec les fonctionnalités `full`, exécute Pingap sur la configuration dans `~/tmp/pingap` avec `--autoreload`, sert l'admin sur `127.0.0.1:3018` (`pingap` / `123123`) et reconstruit lorsque les sources changent. L'admin est intégré au binaire depuis `dist/`, que `make build-web` remplit. La version minimale de Rust prise en charge est 1.96.

### Backend TLS

La compilation par défaut utilise OpenSSL, compilé depuis les sources. Pour rustls :

```bash
cargo build --release --no-default-features --features tls-rustls,full
```

Une compilation rustls propose toujours TLS 1.2 et 1.3 avec les suites de chiffrement propres à rustls, donc les paramètres par serveur `tls_min_version`, `tls_max_version`, `tls_cipher_list` et `tls_ciphersuites` sont refusés lors de la vérification de la configuration. Tout le reste se comporte de la même manière ; les différences sont listées avec la [crate certificate](https://pingap.io/crates/certificate). `pingap --version` indique quel backend un binaire possède.

## 🤝 Contribuer

Les pull requests sont les bienvenues.

- Pour une nouvelle fonctionnalité, veuillez d'abord ouvrir une issue, afin qu'elle puisse être discutée avant l'écriture de tout code.
- Veuillez ne pas ouvrir une pull request uniquement pour corriger une faute de frappe ou le formatage d'un commentaire ; ceux-ci sont corrigés par lots.
- Exécutez `make fmt`, `make lint` et `make test` avant de pousser. La CI exécute les mêmes vérifications sur chaque pull request.
- Une contribution est effectuée sous le [Contributor License Agreement](https://github.com/vicanso/pingap/blob/main/CLA.md), qui est accepté en cochant sa case dans le modèle de pull request : le travail reste le vôtre, et est concédé sous licence au projet selon sa licence.

## 📄 Licence

[Apache License, Version 2.0](https://github.com/vicanso/pingap/blob/main/LICENSE).