0ed9142b1a
Add selection weight section to USAGE.md with decay formula and reference table. Mark feature complete in ROADMAP and TASKS. Update README and PROJECT descriptions.
57 lines
2.2 KiB
Markdown
57 lines
2.2 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
|