multiple urls per entry

2026-11-04 10:56:55 +01:00
1 parent 4bd2088edd
commit 608164dfdd
@@ -0,0 +1,100 @@
+# Xtream proxy: meerdere URLs per upstream-entry
+
+## Doel
+
+Breid `upstreams.json` uit zodat elke entry een lijst van mirror-URLs kan bevatten. Alle URLs binnen een entry delen dezelfde `username`/`password`. Elke URL wordt zelfstandig geprobed en globaal gerankt; bij falen wordt naar elke andere beschikbare URL geprobeerd.
+
+## Beslissingen
+
+- Configformaat wordt **breaking**: alleen `urls` (array), geen `url` meer.
+- Eén entry heeft één `username` en `password`; alle URLs in `urls` gebruiken die credentials.
+- Elke URL wordt een afzonderlijke `Upstream` (zelfde model als nu). Er komt geen aparte entity-laag in de runtime.
+- Selectie en failover blijven globaal over alle URLs, via de bestaande `selectUpstream()` / retry-logica.
+- Deduplicatie blijft op basis van de bestaande key: `origin + basePath | username | password`.
+- Versie wordt opgehoogd naar `3.0.0` vanwege de breaking configwijziging.
+
+Voorbeeldconfig:
+
+```json
+[
+  {
+    "urls": [
+      "http://panel1.example.com:8080",
+      "https://panel1.example.com"
+    ],
+    "username": "user1",
+    "password": "pass1"
+  },
+  {
+    "urls": ["https://panel2.example.com"],
+    "username": "user2",
+    "password": "pass2"
+  }
+]
+```
+
+## Implementatietaken
+
+1. **`src/config.js`**
+   - Lees per entry `urls` in plaats van `url`.
+   - Valideer dat `urls` een niet-lege array is; anders entry overslaan met duidelijke waarschuwing.
+   - Valideer `username` en `password` ongewijzigd als nu.
+   - Valideer elke URL afzonderlijk:
+     - moet een niet-lege string zijn;
+     - trim de waarde vóór opslaan/parsen;
+     - moet met `new URL()` parsebaar zijn;
+     - protocol moet `http:` of `https:` zijn.
+   - Ongeldige URL: alleen die URL overslaan met waarschuwing (entry-nummer + URL-index), niet de hele entry.
+   - Entry met nul geldige URLs: entry overslaan met waarschuwing.
+   - Als `url` aanwezig is zonder `urls`, waarschuw expliciet dat `url` niet meer wordt ondersteund.
+   - Vouw de geldige URLs uit naar losse entries `{ url, username, password }`, zodat de rest van de code ongewijzigd blijft.
+   - Behoud bestaande deduplicatie en state-preservatie in `reloadConfig()` op basis van `Upstream.key`.
+
+2. **`src/upstreams.js`**
+   - Geen selectie- of probewijziging nodig: de uitgevouwen URLs gedragen zich als bestaande upstreams.
+   - Pas eventueel logteksten aan zodat aantallen en resultaten duidelijk over URLs/mirrors gaan in plaats van entries.
+
+3. **`upstreams.json.example`**
+   - Vervang `url` door `urls`-arrays.
+   - Maak het voorbeeld geldige JSON (de huidige `#`-commentaarregels zijn geen geldige JSON).
+   - Documenteer in de voorbeeldtekst/naamgeving dat alle URLs dezelfde credentials delen en onafhankelijk worden geprobed.
+
+4. **Versie en user-agent**
+   - `package.json`: `version` naar `3.0.0`.
+   - `src/settings.js`: standaard `USER_AGENT` naar `xtream-proxy/3.0`.
+   - `Dockerfile` hoeft functioneel niet te wijzigen; controleer alleen of er geen versies/verwijzingen naar het oude formaat in staan.
+
+5. **Documentatie/commentaar in code**
+   - Werk comments bij die nog spreken over één URL per upstream.
+
+## Niet in scope
+
+- Per-URL afwijkende credentials.
+- Een naam/label per entry of per mirror.
+- Prioriteit/weight per mirror; selectie blijft op healthy + busy + latency.
+- Wijzigingen aan de stream-rewrite of load-tracking, anders dan dat elke mirror zijn eigen state krijgt.
+
+## Risico's en aandachtspunten
+
+- **Breaking change:** bestaande configs met `url` werken niet meer. Duidelijk waarschuwen bij het inladen en bijbehorende aanpassing van de voorbeeldconfig opnemen.
+- **Aantallen in logs/health:** `getUpstreams()` bevat nu één item per mirror-URL, niet per entry. Dit is bewust; pas teksten aan waar nodig.
+- **Dubbele labels:** dezelfde URL met verschillende credentials levert twee upstreams met hetzelfde label op in logs/health. Dit bestond al voor losse entries en blijft buiten scope.
+- **Gedeelde accountlimieten:** als mirrors dezelfde account/panel-limiet delen, kan de proxy per URL apart tellen. De bestaande `max_connections`/`active_cons`-probe blijft leidend per URL.
+
+## Validatie
+
+1. `node --check server.js` en `node --check` op alle gewijzigde bestanden in `src/`.
+2. Start de proxy met een tijdelijke config die:
+   - één entry met twee geldige URLs bevat;
+   - één entry met één geldige URL bevat;
+   - één ongeldige URL tussen geldige URLs bevat;
+   - één entry met alleen `url` bevat (moet gewaarschuwd worden overgeslagen).
+3. Controleer in de logs:
+   - het juiste aantal upstreams/URLs;
+   - waarschuwingen voor de ongeldige URL en de oude `url`-entry;
+   - probe-resultaten per URL.
+4. Controleer `/health`:
+   - elke mirror-URL verschijnt als aparte upstream;
+   - `ok`, `selected` en `upstreams` blijven geldig.
+5. Test failover handmatig door één mirror onbereikbaar te maken en te verifiëren dat een request via een andere URL slaagt.
+6. Test deduplicatie: dezelfde URL + credentials twee keer in de config levert één upstream op.