projects/.kilo/plans/1793785888951-upstream-url-lists.md

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:

[
  {
    "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.