fc1dea70f4
Add warm start and chain pre-flight sections to USAGE. Mark both features complete in ROADMAP and TASKS. Remove implemented items from TODO. Update README, PROJECT, and CHEATSHEET.
61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
# 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
|
|
- **Chain pre-flight** -- static chain tested before pool health tests; skip on failure
|
|
- **Warm start** -- quick-test alive subset on restart, defer full test to background
|