eddcc5f615
Add failure backoff and stale expiry sections to USAGE. Document pool= field in metrics output. Update ROADMAP, TASKS, TODO with completed items and remaining suggestions. Add metrics example to CHEATSHEET.
2.3 KiB
2.3 KiB
s5p -- Project
Purpose
A lightweight SOCKS5 proxy server that chains connections through Tor and/or arbitrary proxy hops (SOCKS4, SOCKS5, HTTP CONNECT).
Motivation
Existing solutions (proxychains-ng) rely on LD_PRELOAD hacks, only work
on Linux, and intercept at the library level. s5p is a proper SOCKS5 server
that any application can use natively -- no injection required.
Architecture
TCP tunnel tunnel
Client -------> s5p -------> Hop 1 -------> Hop 2 -------> Target
SOCKS5 proto1 proto2 protoN
- server.py -- asyncio SOCKS5 server, bidirectional relay, signal handling
- proto.py -- protocol handshakes (SOCKS5, SOCKS4/4a, HTTP CONNECT), chain builder
- config.py -- YAML config loading, proxy URL parsing, pool config
- pool.py -- managed proxy pool (multi-source, health-tested, persistent)
- source.py -- legacy proxy source (single HTTP API, kept for backward compat)
- cli.py -- argparse CLI, logging setup, cProfile support
Deployment
| Method | Command |
|---|---|
| Local venv | pip install -e . then s5p -c config/s5p.yaml |
| Container | make build && make up (Alpine, ~59MB) |
Container mounts ./src and ./config/s5p.yaml read-only at runtime.
No application code is baked into the image.
Dependencies
| Package | Purpose |
|---|---|
| pyyaml | Config file parsing |
All other functionality uses Python stdlib (asyncio, socket, struct).
Design Decisions
- No LD_PRELOAD -- clean SOCKS5 server, works with any client
- asyncio -- single-threaded event loop, efficient for I/O-bound proxying
- Domain passthrough -- never resolve DNS locally to prevent leaks
- Tor as a hop -- no special Tor handling; it's just
socks5://127.0.0.1:9050 - Graceful shutdown -- SIGTERM/SIGINT handled in the event loop for clean container stops
- Config split -- tracked example template, gitignored live config with real addresses
- Proxy pool -- multi-source (API + file), health-tested, persistent, auto-cleaned
- Weighted selection -- recently-tested proxies preferred via recency decay weight
- Failure backoff -- connection failures penalize proxy weight for 60s, avoids retry waste
- Stale expiry -- proxies dropped from sources evicted after 3 refresh cycles if not alive