Enhance gluetun PIA WireGuard rotator with health check and recovery logic. Introduce new environment variables for health check interval and unhealthy cooldown. Refactor entrypoint.py to manage Gluetun health status and implement two-step recovery for unhealthy states. Update rotation logic to account for health status during scheduled rotations.

Dockers/gluetun-pia-wireguard-rotator/README.md

@@ -1,12 +1,13 @@
 # gluetun-pia-wireguard-rotator
 
-Sidecar die op een cron-schema (en bij container-start) de **snelste** PIA WireGuard-server kiest (TCP-latency), lokaal een keypair maakt, via PIA `addKey` registreert, `wg0.conf` op het gedeelde gluetun-volume schrijft, en afhankelijke containers herstart.
+Sidecar die de **snelste** PIA WireGuard-server kiest (TCP-latency), lokaal een keypair maakt, via PIA `addKey` registreert, `wg0.conf` schrijft, en Gluetun (+ sidecars) herstart. Pollt Gluetun-health elke 10s en herstelt bij `unhealthy`.
 
 ## Vereisten
 
 - Gluetun met `VPN_SERVICE_PROVIDER=custom` en `VPN_TYPE=wireguard`
-- Gedeeld volume met gluetun (bijv. `/var/dockers/m3u-filter-pia:/gluetun` op gluetun, `/config` op de rotator)
-- Docker socket (voor `docker restart` van gluetun en eventuele sidecar-containers)
+- Docker **healthcheck** op de Gluetun-container (anders werkt alleen cron)
+- Gedeeld volume met gluetun (bijv. `/var/dockers/m3u-filter-pia:/gluetun` ↔ `/config`)
+- Docker socket (voor `docker restart` / health inspect)
 - Actief PIA-abonnement
 
 ## Environment variables
@@ -17,11 +18,9 @@ Sidecar die op een cron-schema (en bij container-start) de **snelste** PIA WireG
 |----------|-------------|
 | `PIA_USER` | PIA-gebruikersnaam |
 | `PIA_PASS` | PIA-wachtwoord |
-| `PIA_REGIONS` | CSV (`nl_amsterdam,france,belgium`) of JSON-array (`["nl_amsterdam","france"]`) |
+| `PIA_REGIONS` | CSV (`nl_amsterdam,france,belgium`) of JSON-array |
 
-Region-IDs komen uit de PIA serverlist (niet de OpenVPN-namen uit Gluetun's ingebouwde PIA-provider).
-
-Lijst opvragen:
+Region-IDs komen uit de PIA serverlist.
 
 ```bash
 docker run --rm --entrypoint /opt/venv/bin/python \
@@ -33,36 +32,30 @@ docker run --rm --entrypoint /opt/venv/bin/python \
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `RESTART_CONTAINERS` | — | CSV of JSON-array met **extra** containers om te herstarten na gluetun (sidecars). Voorbeeld: `SabNZBd,qbittorrent,Spotweb` |
-| `GLUETUN_CONTAINER` | `m3u-filter-vpn` | Gluetun-container; wordt **altijd als eerste** herstart |
-| `WG_CONFIG_PATH` | `/config/wireguard/wg0.conf` | Pad waar `wg0.conf` wordt geschreven |
-| `ROTATOR_STATE_PATH` | `/config/rotator-state.json` | Laatste rotatie-metadata |
-| `ROTATE_CRON` | `0 3 * * *` | 5-veld cron-expressie, in `TZ`. Macros: `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly` |
-| `REGION_SELECT` | `fastest` | `fastest` = laagste TCP-latency; `random` = willekeurige regio/server |
+| `RESTART_CONTAINERS` | — | Extra containers na gluetun (sidecars) |
+| `GLUETUN_CONTAINER` | `m3u-filter-vpn` | Gluetun-container (eerste restart + health poll) |
+| `WG_CONFIG_PATH` | `/config/wireguard/wg0.conf` | Pad voor `wg0.conf` |
+| `ROTATOR_STATE_PATH` | `/config/rotator-state.json` | Rotatie-metadata |
+| `ROTATE_CRON` | `0 3 * * *` | Periodieke latency-check (soft) |
+| `HEALTH_CHECK_INTERVAL` | `10` | Seconden tussen health/cron polls |
+| `UNHEALTHY_ROTATE_COOLDOWN` | `60` | Wachttijd na unhealthy-rotatie om healthy te worden |
+| `REGION_SELECT` | `fastest` | `fastest` of `random` |
 | `LATENCY_PORT` | `1337` | TCP-poort voor latency-probes |
 | `LATENCY_TIMEOUT_SECONDS` | `2` | Timeout per probe |
-| `LATENCY_SAMPLES` | `2` | Aantal samples per server-IP (gemiddelde) |
-| `LATENCY_SWITCH_MARGIN_MS` | `15` | Alleen switchen als de winst ≥ deze marge is |
-| `SERVERLIST_CACHE_PATH` | `/config/cache/pia-serverlist.json` | Disk-cache voor PIA serverlist |
-| `SERVERLIST_CACHE_TTL` | `24h` | Cache zonder refresh (`Ns`/`Nm`/`Nh`/`Nd` of seconden) |
-| `SERVERLIST_CACHE_MAX_AGE` | `168h` | Max leeftijd; stale fallback bij fetch-fout |
-| `TOKEN_CACHE_PATH` | `/config/cache/pia-token.json` | Disk-cache voor PIA auth-token |
-| `TOKEN_CACHE_TTL` | `20h` | Hergebruik token i.p.v. opnieuw inloggen |
-| `PIA_CA_PATH` | `/config/cache/ca.rsa.4096.crt` | Gecachete PIA CA voor `addKey` TLS |
-| `FORCE_TOKEN_REFRESH` | `false` | `true` = token-cache negeren |
-| `RATE_LIMIT_WAIT_SECONDS` | `3600` | Cooldown bij PIA rate-limit (blijft gelden na container-restart) |
-| `RATE_LIMIT_PATH` | `/config/cache/pia-rate-limit.json` | Persistente cooldown-timestamp |
-| `TZ` | `Europe/Brussels` | Tijdzone voor scheduling |
+| `LATENCY_SAMPLES` | `2` | Samples per IP |
+| `LATENCY_SWITCH_MARGIN_MS` | `15` | Soft stickiness bij cron (niet bij unhealthy force) |
+| `SERVERLIST_CACHE_PATH` | `/config/cache/pia-serverlist.json` | Serverlist-cache |
+| `SERVERLIST_CACHE_TTL` | `24h` | Cache-TTL |
+| `SERVERLIST_CACHE_MAX_AGE` | `168h` | Max stale age |
+| `TOKEN_CACHE_PATH` | `/config/cache/pia-token.json` | Token-cache |
+| `TOKEN_CACHE_TTL` | `20h` | Token hergebruik |
+| `PIA_CA_PATH` | `/config/cache/ca.rsa.4096.crt` | PIA CA voor addKey |
+| `FORCE_TOKEN_REFRESH` | `false` | Token-cache negeren |
+| `RATE_LIMIT_WAIT_SECONDS` | `3600` | Cooldown bij PIA rate-limit |
+| `RATE_LIMIT_PATH` | `/config/cache/pia-rate-limit.json` | Persistente rate-limit cooldown |
+| `TZ` | `Europe/Brussels` | Tijdzone |
 
-`ROTATE_CRON` voorbeelden: `0 */6 * * *`, `0 3 * * 1-5`, `@hourly`. Quote in Compose: `'ROTATE_CRON=0 3 * * *'`.
-
-## Output
-
-- `wireguard/wg0.conf` — Gluetun leest dit als `/gluetun/wireguard/wg0.conf` (overschrijft `WIREGUARD_*` env-vars)
-- `rotator-state.json` — gekozen region/server, latency, timestamps
-- `cache/` — serverlist, token, PIA CA
-
-## Compose-integratie
+## Compose
 
 ```yaml
   gluetun-pia-wireguard-rotator:
@@ -76,8 +69,7 @@ docker run --rm --entrypoint /opt/venv/bin/python \
       - PIA_REGIONS=nl_amsterdam,france,belgium
       - GLUETUN_CONTAINER=downloaders-vpn
       - RESTART_CONTAINERS=SabNZBd,qbittorrent,nzbhydra2,Spotweb
-      - 'ROTATE_CRON=0 3 * * *'
-      # optioneel: REGION_SELECT=random
+      - 'ROTATE_CRON=0 */6 * * *'
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - /var/dockers/m3u-filter-pia:/config
@@ -85,35 +77,15 @@ docker run --rm --entrypoint /opt/venv/bin/python \
       - m3u-filter-vpn
 ```
 
-### Gluetun opschonen (aanbevolen na eerste succesvolle rotatie)
-
-Verwijder uit gluetun zodra `wg0.conf` bestaat:
-
-- `WIREGUARD_ENDPOINT_IP`
-- `WIREGUARD_PUBLIC_KEY`
-- `WIREGUARD_PRIVATE_KEY`
-- `WIREGUARD_ADDRESSES`
-
-Behoud minimaal:
-
-```yaml
-    environment:
-      - VPN_SERVICE_PROVIDER=custom
-      - VPN_TYPE=wireguard
-```
-
-## Deploy
-
-1. Push/build image (`Dockers/gluetun-pia-wireguard-rotator/**` → `bramkel/gluetun-pia-wireguard-rotator:latest`)
-2. `docker compose up -d gluetun-pia-wireguard-rotator`
-3. Logs: `docker logs gluetun-pia-wireguard-rotator`
-
 ## Gedrag
 
-1. Latency meten over WG-servers in `PIA_REGIONS` (of random)
-2. **Pin** de snelste server-IP (niet alleen regio)
-3. Altijd nieuw keypair + `addKey` (reauth), daarna containers herstarten
-4. Caches: serverlist, token (~20u), CA-cert — alleen om overbodige API-calls te beperken
-5. Bij rate-limit: cooldown van `RATE_LIMIT_WAIT_SECONDS` (default 1 uur), **persistent op disk** zodat restarts geen extra API-calls doen; daarna opnieuw proberen. Andere token-endpoints worden eerst nog geprobeerd.
+1. **Startup:** force-rotatie (beste server + nieuwe keypair)
+2. **Elke `HEALTH_CHECK_INTERVAL`:** health van `GLUETUN_CONTAINER` checken
+3. **Unhealthy recovery (max 2 stappen):**
+   - Stap 1: force beste server + nieuwe keypair (keypair kan invalid zijn)
+   - Wacht tot `UNHEALTHY_ROTATE_COOLDOWN` of tot healthy
+   - Nog unhealthy → stap 2: exclude die IP, force runner-up (#2 latency)
+4. **Cron due:** latency opnieuw meten; **zelfde beste server** → geen token/addKey/restarts
+5. Rate-limit: persistente cooldown, daarna retry
 
-**Let op:** zet gluetun **niet** in `RESTART_CONTAINERS`; gebruik `GLUETUN_CONTAINER`. Elke echte rotatie geeft korte downtime.
+**Let op:** zet gluetun niet in `RESTART_CONTAINERS`. Elke echte rotatie geeft korte downtime.