docs: add proxy source API documentation

README.md

@@ -11,6 +11,7 @@ through configurable chains of SOCKS4, SOCKS5, and HTTP CONNECT proxies.
 - Per-hop authentication (username/password)
 - DNS leak prevention (domain names forwarded to proxies, never resolved locally)
 - Tor integration (Tor is just another SOCKS5 hop)
+- Dynamic proxy source: fetch proxies from an HTTP API, rotate per-connection
 - Container-ready (Alpine-based, podman/docker)
 - Graceful shutdown (SIGTERM/SIGINT)
 - Pure Python, asyncio-based, minimal dependencies
@@ -59,8 +60,12 @@ timeout: 10
 
 chain:
   - socks5://127.0.0.1:9050          # Tor
-  - socks5://user:pass@proxy:1080    # post-Tor proxy
-  - http://proxy2:8080               # HTTP CONNECT proxy
+
+proxy_source:
+  url: http://10.200.1.250:8081/proxies
+  proto: socks5                       # optional filter
+  limit: 1000
+  refresh: 300                        # cache refresh (seconds)
 ```
 
 `config/s5p.yaml` is gitignored; `config/example.yaml` is the tracked template.
@@ -68,12 +73,13 @@ chain:
 ## CLI Reference
 
 ```
-s5p [-c FILE] [-l [HOST:]PORT] [-C URL[,URL,...]] [-t SEC] [-v|-q] [--cprofile [FILE]]
+s5p [-c FILE] [-l [HOST:]PORT] [-C URL[,URL,...]] [-S URL] [-t SEC] [-v|-q]
 
 Options:
   -c, --config FILE        YAML config file
   -l, --listen [HOST:]PORT Listen address (default: 127.0.0.1:1080)
   -C, --chain URL[,URL]    Comma-separated proxy chain
+  -S, --proxy-source URL   Proxy source API URL
   -t, --timeout SEC        Per-hop timeout (default: 10)
   -v, --verbose            Debug logging
   -q, --quiet              Errors only
@@ -84,9 +90,10 @@ Options:
 ## How Chaining Works
 
 ```
-Client -> s5p -> Hop1 -> Hop2 -> ... -> HopN -> Destination
+Client -> s5p -> [static chain] -> [random proxy from source] -> Destination
 ```
 
 s5p connects to Hop1 via TCP, negotiates the hop protocol (SOCKS5/4/HTTP),
-then over that tunnel negotiates with Hop2, and so on. The final hop connects
-to the actual destination. Each hop only sees its immediate neighbors.
+then over that tunnel negotiates with Hop2, and so on. If a proxy source is
+configured, a random proxy is appended to the chain per-connection. Each hop
+only sees its immediate neighbors.