Files

user a5e634e406 docs: update project docs for SIGHUP reload and dead proxy reporting

Add hot reload section to USAGE with reloadable settings table.
Add dead proxy reporting section with report_url config and payload
format. Update example.yaml, ROADMAP, TASKS, TODO, CHEATSHEET.

2026-02-15 16:05:39 +01:00

2.7 KiB

Raw Blame History

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
SIGHUP reload -- re-read config, update pool settings, re-fetch sources
Dead reporting -- POST evicted proxies to upstream API for list quality feedback

2.7 KiB Raw Blame History